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 with your API definitions and SDK generation configuration
• SDK repositories for each SDK (TypeScript, Python, Go, etc.)

$
├─ company-repo                 # Source repository
>
│  ├─ .github/workflows/         # 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
>
│  ├─ .github/workflows/        # Generated by Fern
>
│  ├─ scripts/
>
│  ├─ src/
>
│  ├─ tests/
>
│  └─ .fernignore               # Files Fern shouldn't modify
>
├─ 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.77.5"
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 points to your API definition and specifies which SDKs to generate.

1
# Your API definition
2
api: 
3
  specs: 
4
    - openapi: ./openapi-1.yml
5
6
# SDK generators
7
groups:
8
  ts-sdk:
9
    generators:
10
      - name: fernapi/fern-typescript-sdk
11
        version: 2.12.3
12
        github:
13
          repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK
14
  
15
  python-sdk:
16
    generators:
17
      - name: fernapi/fern-python-sdk
18
        version: 4.28.5
19
        github:
20
          repository: your-organization/python-sdk-repo # Location of Python SDK

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

API definition file

See Project structure (API Definitions) for details on organizing your API definition files and working with multiple APIs.

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.