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.)

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’s initialized with your API definitions and a top-level sdk-config.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. To keep every project in your organization on a compatible version, set an organization-wide CLI version policy.

{
  "organization": "plant-catalog",
  "version": "5.23.3"
}

sdk-config.yml

The sdk-config.yml file declares your API spec location in source.specs and lists one target per SDK language in targets. Settings at the top level apply to every target, and each target can override them.

schemaVersion: sdk-config/v1
sdkName: Plant Store
# API declaration
source:
  specs:
    - id: plant-store
      type: openapi
      path: ./openapi/openapi.yml
# SDK generation
targets:
  - language: typescript
    package:
      packageName: "@plant-store/sdk"
    output:
      delivery: github
      github:
        repository: your-organization/typescript-sdk-repo
  - language: python
    package:
      packageName: plant-store
    output:
      delivery: github
      github:
        repository: your-organization/python-sdk-repo

Each language can appear once per file. Generate one target with fern generate --target typescript, or every target with fern generate.

delivery: github targets GitHub repositories only — Fern doesn’t push SDKs to GitLab or other providers. The sdk-config.yml reference covers every configuration option.

API definition file

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