Project structure

Configuring fern starts with the fern folder, which contains your API definitions, SDK generators, and your CLI version.

Fern recommends a multi-repository structure with your fern folder in a source repository (containing your API definitions and generation configuration) and each generated SDK in its own separate repository.

Directory structure

When you run fern init (for the Fern Definition) or fern init --spec-type path/to/spec (for other specs), your fern folder is initialized with the following files:

Core configuration files

fern.config.json

The fern.config.json file stores your organization name and the Fern CLI version. Pinning the version provides deterministic builds.

1
{
2
  "organization": "plant-catalog",
3
  "version": "4.42.0"
4
}

generators.yml

The generators.yml file is required for OpenAPI/AsyncAPI to declare your API specification location. This also enables API Reference documentation.

1
api:
2
  specs:
3
    - openapi: ./openapi/openapi.yml

For Fern Definition, no generators.yml is needed to generate API Reference docs. Fern automatically detects your API by checking for a definition/ directory.

For SDK generation, generators.yml is required for all specification formats. Add a groups section to configure which SDKs to generate. See the SDKs project structure for details.

API definition file

For Fern Definition, your API configuration is split across two files: api.yml for API-wide configuration and separate .yml files for your actual endpoint and type definitions. See What is a Fern Definition? for more information.

For the other specification formats (OpenAPI, AsyncAPI, OpenRPC, and gRPC), you’ll have a single self-contained specification file.

Where to store your API definition

There are three common ways to manage your API definition:

• Commit directly into your Fern repository (recommended). Check your API definition file into the same repository that contains your Fern configuration. This is the simplest approach if you don’t maintain the definition elsewhere.
• Sync from a source code repository. Store your API definition in the same repo as your API source code and sync updates into your Fern repository. You can automate this with the fern api update CLI command or the sync-openapi GitHub Action.
• Host at a public URL. Serve the definition from a publicly accessible endpoint and configure the origin field in generators.yml so Fern can fetch it. This is useful when you want a single canonical definition that multiple consumers can reference.

Multiple APIs

Fern supports two approaches for working with multiple API definitions. Both require an apis folder — this folder must use that exact name.

1. Separate SDKs for each API - Each API generates its own independent set of SDK packages (e.g., @company/user-api, @company/payments-api or versioned like @company/sdk-v1, @company/sdk-v2)
2. Combined SDKs from multiple APIs - Multiple APIs merge into a single SDK package with optional namespacing (e.g., client.users, client.payments or versioned like client.v1, client.v2)

Separate SDKs for each API

Use this approach when each API should generate its own independent set of SDKs. This works for both distinct APIs (e.g., user-api and payments-api) and versioned APIs where you want each version to be independently installable (e.g., @company/sdk-v1, @company/sdk-v2).

1
api:
2
  specs:
3
    - openapi: openapi.yml # Spec file in the same folder
4
groups:
5
  # SDK generator configuration

Combined SDKs from multiple APIs

Use this approach when you want to merge multiple APIs into a single SDK package, with optional namespacing to organize them. This works for both distinct APIs and versioned APIs, though it increases package size as all APIs are bundled together.

For versioned APIs, namespacing lets you access different versions like client.v1 and client.v2 within the same package.

1
api:
2
  specs:
3
    - openapi: user-api/openapi.yml
4
    - openapi: payments-api/openapi.yml
5
groups:
6
  # SDK generator configuration

1
api:
2
  specs:
3
    - openapi: apis/user-api/openapi.yml
4
    - namespace: payments
5
      openapi: apis/payments-api/openapi.yml
6
groups:
7
  # SDK generator configuration