Overview

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.

Examples

See Cohere’s fern folder and TypeScript and Python SDK repositories.

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

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

fern.config.json
1{
2  "organization": "plant-catalog",
3  "version": "<Markdown src="/snippets/version-number-cli.mdx"/>"
4}

When working with a locally installed CLI, set version to "*". See Install Fern CLI locally for details.

generators.yml

The generators.yml file specifies which SDKs to generate. For OpenAPI, it also points to the location of your spec. For Fern Definition, Fern automatically detects your spec when your definition/ folder is at the same level as generators.yml.

generators.yml
1# Your API definition
2api: 
3  specs: 
4    - openapi: ./openapi-1.yml
5
6# SDK generators
7groups:
8  ts-sdk:
9    generators:
10      - name: fernapi/fern-typescript-sdk
11        version: <Markdown src="/snippets/version-number-ts.mdx"/>
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: <Markdown src="/snippets/version-number-python.mdx"/>
19        github:
20          repository: your-organization/python-sdk-repo # Location of Python SDK
Examples

See Cohere’s generators.yml file and Vapi’s generators.yml file.

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.