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 multi-repository structure containing:

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

$
├─ company-repo                 # Source repository
>
│  ├─ .github.workflows         # Contains publishing workflows for all SDKs
>
│  └─ fern/
>
│     ├─ fern.config.json       # Root-level config
>
│     ├─ generators.yml         # References SDK repos
>
│     └─ definition/ 
>
         ├─ overrides.yml       # Optional overrides file
>
│        └─ api.yml             # Your API definition
>
├─ typescript-sdk-repo          # SDK repository
>
├─ python-sdk-repo              # SDK repository  
>
└─ go-sdk-repo                  # SDK 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 source 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. It contains a group for each SDK generator and points to the corresponding SDK’s repository:

1
groups:
2
  ts-sdk:
3
    generators:
4
      - name: fernapi/fern-typescript-sdk
5
        version: 2.9.3
6
        github:
7
          repository: your-organization/typescript-sdk-repo
8
  
9
  python-sdk:
10
    generators:
11
      - name: fernapi/fern-python-sdk
12
        version: 4.26.2
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.

SDK repository structure

Each SDK has its own repository with the following structure:

$
typescript-sdk-repo/            # Individual SDK repository
>
├─ .github/workflows/           # Generated by Fern
>
├─ 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 source repository, plus one repository for each SDK
2. Install Fern GitHub App: Install the Fern GitHub App on all repositories
3. Configure generators.yml: In your generators.yml, add a reference to each SDK repository.

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