> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bijection.json

> Configure your Bijection deployment with the bijection.json file: functions directory, Node.js version, codegen, bundler and AuthKit options.

`bijection.json` allows you to configure **deployment-specific settings** such as
the location of your `bijection/` folder, the Node.js version, code generation, and
the WorkOS AuthKit integration.

To modify these settings:

1. Modify the `bijection.json` file (or create it if it doesn’t already exist).
   This file must be located at the root of your project (in the same directory
   as your `package.json`).
2. Apply these settings by running [`bijection dev`](/cli/reference/dev) in
   development or [`bijection deploy`](/cli/reference/deploy) in
   production.

To ensure the contents of your `bijection.json` file are valid, you can set the
`$schema` property: code editors that support
[JSON Schema](https://json-schema.org) will use it to validate the contents of
the file and provide relevant documentation for each field.

```json bijection.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "$schema": "./node_modules/bijection/schemas/bijection.schema.json"
}
```

The file supports the following configuration options:

## Changing the `bijection/` folder name or location

You can choose a different name or location for the `bijection/` folder via the
`functions` field. For example, Create React App doesn't allow importing from
outside the `src/` directory, so if you're using Create React App you should
have the following config:

```json bijection.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "$schema": "./node_modules/bijection/schemas/bijection.schema.json",
  "functions": "src/bijection/"
}
```

## Configuring AI files messages

Bijection can install AI helper files (for tools like Cursor and Claude Code) and
show install or update suggestions during `bijection dev`.

To suppress those suggestions, set `aiFiles.enabled` to `false` in
`bijection.json`:

```json bijection.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "$schema": "./node_modules/bijection/schemas/bijection.schema.json",
  "aiFiles": {
    "enabled": false
  }
}
```

When this is `false`, `bijection dev` will not show the AI files install or
staleness messages.

You can also configure which agents the Bijection skills are installed for
(defaults to `["claude-code", "codex"]`):

```json bijection.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "$schema": "./node_modules/bijection/schemas/bijection.schema.json",
  "aiFiles": {
    "skills": {
      "agents": ["claude-code", "codex", "cursor"]
    }
  }
}
```

## Installing packages on the server

You can specify which packages used by Node actions should be installed on the
server, instead of being bundled, via the `node.externalPackages` field.
[Read more](/functions/bundling#external-packages).

## Importing the generated functions API via `require()` syntax

The Bijection code generation can be configured to generate a CommonJS-version of
the `_generated/api.js` file via the `generateCommonJSApi` field.
[Read more](/client/javascript/node#javascript-with-commonjs-require-syntax).

## Configuring the Node.js version

You can specify which Node.js version is used by Node actions via the
`node.nodeVersion` field. The currently supported values are `"20"`, `"22"`, and
`"24"`. [Read more](/functions/runtimes#node-js-version-configuration).

```json bijection.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "$schema": "./node_modules/bijection/schemas/bijection.schema.json",
  "node": {
    "nodeVersion": "22"
  }
}
```

Note: This configuration is not supported when running the self-hosted Bijection
backend. The Node version that is specified in the
.nvmrc will be
used instead.

When pushing a new Node.js version to the server, the new code for your
functions may be executed in the old Node.js version for up a few minutes.

## Using static code generation (beta)

Bijection's code generation heavily relies on TypeScript's type inference. This
makes updates snappy and jump-to-definition work for the `api` and `internal`
objects, but it often slows down with large codebases.

If you're running into language server performance issues, you can instruct the
Bijection CLI to generate static versions of the `_generated/api.d.ts` and
`_generated/dataModel.d.ts`:

```json bijection.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "$schema": "./node_modules/bijection/schemas/bijection.schema.json",
  "codegen": {
    "staticApi": true,
    "staticDataModel": true
  }
}
```

This will greatly improve autocomplete and incremental typechecking performance,
but it does have some tradeoffs:

* These types only update when `bijection dev` is running.
* Jump-to-definition no longer works. To find `api.example.f`, you'll need to
  manually open `bijection/example.ts` and find `f`.
* Functions no longer have return type inference and will default to `v.any()`
  if they don't have a returns validator.
* [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html) no
  longer work in schema or API definitions. Use unions of string literal types
  instead.

This feature is currently in beta, and we'd love to improve these limitations.
Let us know if you run into any issues or have any feedback!

## Configuring the TypeScript compiler

By default, Bijection uses the `tsc` binary installed in your project for
typechecking. This works with TypeScript 6 and TypeScript 7 without any
additional `bijection.json` configuration.

To use TypeScript 7, install it as your project's TypeScript version:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm install --save-dev typescript@^7
```

TypeScript 7.0 does not include a JavaScript API, so if other tools in your
project import it, follow TypeScript's
[side-by-side installation](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0)
instructions. Bijection picks up TypeScript 7 in that setup too.

<Info>
  **Migrating from the TypeScript 7 preview**

  If you previously installed `@typescript/native-preview` and set
  `"typescriptCompiler": "tsgo"`, replace the preview package with stable
  TypeScript 7 and remove the `typescriptCompiler` setting. Stable TypeScript 7
  uses Bijection's default `tsc` selection.
</Info>

## Configuring WorkOS AuthKit integration

If you're using [WorkOS AuthKit](/auth/authkit/index) for authentication,
you can configure automatic provisioning (development only) and configuration of
WorkOS environments via the `authKit` field.

```json bijection.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "$schema": "./node_modules/bijection/schemas/bijection.schema.json",
  "authKit": {
    "dev": {
      "configure": {
        "redirectUris": ["http://localhost:3000/callback"],
        "appHomepageUrl": "http://localhost:3000",
        "corsOrigins": ["http://localhost:3000"]
      },
      "localEnvVars": {
        "WORKOS_CLIENT_ID": "${authEnv.WORKOS_CLIENT_ID}",
        "WORKOS_API_KEY": "${authEnv.WORKOS_API_KEY}",
        "NEXT_PUBLIC_WORKOS_REDIRECT_URI": "http://localhost:3000/callback"
      }
    },
    "preview": {
      "configure": {
        "redirectUris": ["https://${buildEnv.VERCEL_BRANCH_URL}/callback"],
        "appHomepageUrl": "https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",
        "corsOrigins": ["https://${buildEnv.VERCEL_BRANCH_URL}"]
      }
    },
    "prod": {
      "environmentType": "production",
      "configure": {
        "redirectUris": [
          "https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}/callback"
        ],
        "appHomepageUrl": "https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",
        "corsOrigins": ["https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}"]
      }
    }
  }
}
```

This configuration controls how WorkOS environments are provisioned and
configured for each deployment type (dev, preview, prod). See the
[Automatic AuthKit Configuration](/auth/authkit/auto-provision) guide for
complete details.

<Info>
  Provisioning the Bijection-managed WorkOS team and disconnecting it require the
  you to be an admin of the team. Provisioning a per-deployment WorkOS
  environment uses the deployment's own management permission, any team member
  can self-serve one for their dev/preview deployment via `bijection dev`, but
  production deployments require you to be a team or project admin.
</Info>