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": "2.4.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.

Multiple APIs

Fern supports two approaches for working with multiple API definitions:

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 let 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