Project structure

Before generating SDKs with Fern, set up the proper GitHub repository structure to house your API definitions and SDK code so it’s intuitive for you and your users to access, maintain, and update code.

Repository architecture

Fern recommends a parent-child repository structure containing:

• Parent repository: Contains your API definitions and SDK generation configuration
• Child repositories: Separate repositories for each SDK (TypeScript, Python, Go, etc.)

$
├─ company-repo                 # Parent repository
>
│  └─ fern/
>
│     ├─ fern.config.json       # Root-level config
>
│     ├─ generators.yml         # References child repos
>
│     └─ definition/ 
>
         ├─ overrides.yml       # Optional overrides file
>
│        └─ api.yml             # Your API definition
>
├─ typescript-sdk-repo          # Child repository
>
├─ python-sdk-repo              # Child repository  
>
└─ go-sdk-repo                  # Child repository

This separation allows you to manage API definitions centrally while keeping each SDK in its own repository for independent versioning and distribution.

Core configuration files

The parent repository contains a fern/ folder that is initialized with your API definitions and a top-level generators.yml file.

fern.config.json

Every fern folder has a single fern.config.json file. This file stores the organization name and the version of the Fern CLI that you are using:

1
{
2
    "organization": "your-organization",
3
    "version": "0.65.27"
4
}

Every time you run a fern CLI command, the CLI downloads itself at the correct version to ensure determinism.

generators.yml

The generators.yml file specifies which SDKs to generate and where to publish them. It acts as the bridge between your API definitions and your SDK repositories. For SDK generation, it contains a group for each SDK and points to the corresponding child repository:

1
groups:
2
  ts-sdk:
3
    generators:
4
      - name: fernapi/fern-typescript-sdk
5
        version: 2.8.2
6
        github:
7
          repository: your-organization/typescript-sdk-repo
8
  
9
  python-sdk:
10
    generators:
11
      - name: fernapi/fern-python-sdk
12
        version: 4.25.9
13
        github:
14
          repository: your-organization/python-sdk-repo

See the generators.yml reference page for complete configuration options.

API definition file

For information on how to structure your API definition files, see Project structure (API Definitions).

Optional: overrides.yml file

You can optionally add an overrides.yml file to customize your API definition without modifying the original spec file. For more information, see Overrides.

Child repository structure

Each SDK has its own repository with the following structure:

$
typescript-sdk-repo/            # Individual SDK repository
>
├─ .github/workflows/           # Publishing workflows
>
├─ scripts/
>
├─ src/
>
├─ tests/
>
└─ .fernignore                  # Files Fern shouldn't modify

Fern generates most of these files automatically, including preserving any custom code you’ve added.

Setup instructions

1. Create repositories: Set up your parent repository and one child repository for each SDK
2. Install Fern GitHub App: Install the Fern GitHub App on all repositories (parent and children)
3. Configure generators.yml: Add each child repository to your generators.yml file

Multiple API definitions

The fern folder can house multiple API definitions. When you have multiple APIs, nest your definition files within an apis folder.

Each API must also have a separate generators.yml file that specifies the location of the API definition and configures SDK generation.

$
fern/
>
  ├─ fern.config.json
>
  ├─ generators.yml # Optional: top-level configuration for all APIs
>
  └─ apis/
>
    └─ first-api/ # First API
>
        ├─ generators.yml # Required: points to API spec
>
        └─ openapi/
>
          ├─ openapi.yml # API Definition file
>
    └─ second-api/ # Second API
>
        ├─ generators.yml # Required: points to API spec
>
        └─ openapi/
>
          ├─ openapi.yml # API Definition file

SDK generation

To specify the API for SDK generation use the --api flag:

$
fern generate --api public-api