> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Project structure

> Describes the Fern folder structure

Configuring fern starts with the `fern` folder, which contains your API definitions,
SDK generators, and your CLI version.

Fern recommends a multi-repository structure with your fern folder in a source repository (containing your API definitions and generation configuration) and [each generated SDK in its own separate repository](/learn/sdks/overview/project-structure).

## Directory structure

When you run `fern init --spec-type path/to/spec`, your fern folder is initialized with the following files:

## Core configuration files

Beyond the core files, you can optionally use an [overlays (OpenAPI)](/learn/api-definitions/openapi/overlays) or [overrides](/learn/api-definitions/asyncapi/overrides) file to customize your API definition without modifying the original spec.

### `fern.config.json`

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

```json title="fern.config.json"
{
  "organization": "plant-catalog",
  "version": "5.23.3"
}
```

When working with a locally installed CLI, set `version` to `"*"`. See [Install Fern CLI locally](/learn/cli-api-reference/cli-reference/overview#install-fern-cli-locally) for details.

### `generators.yml`

The `generators.yml` file declares your API specification location. This also enables [API Reference documentation](/learn/docs/api-references/overview).

```yaml title="generators.yml"
api:
  specs:
    - openapi: ./openapi/openapi.yml
```

For SDK generation, `generators.yml` is required. Add a `groups` section to configure which SDKs to generate. See the [SDKs project structure](/learn/sdks/overview/project-structure#generatorsyml) for details.

### API definition file

For [OpenAPI](/learn/api-definitions/openapi/overview), [AsyncAPI](/learn/api-definitions/asyncapi/overview), [OpenRPC](/learn/api-definitions/openrpc/overview), and [gRPC](/learn/api-definitions/grpc/overview), you'll have a single self-contained specification file.

## Where to store your API definition

There are four common ways to manage your API definition:

* **Commit directly into your Fern repository (recommended).** Check your API definition file into the same repository that contains your Fern configuration. This is the simplest approach if you don't maintain the definition elsewhere.
* **Sync from a source code repository.** Store your API definition in the same repo as your API source code and sync updates into your Fern repository. You can automate this with the [`fern api update`](/learn/cli-api-reference/cli-reference/commands#fern-api-update) CLI command or the [sync-openapi GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification).
* **Host at a public URL.** Serve the definition from a publicly accessible endpoint and configure the [`origin`](/learn/sdks/reference/generators-yml#openapi) field in `generators.yml` so Fern can fetch it. This is useful when you want a single canonical definition that multiple consumers can reference.
* **Reference from a remote git repository.** Point [`openapi`](/learn/sdks/reference/generators-yml#openapi), [`asyncapi`](/learn/sdks/reference/generators-yml#asyncapi), or proto [`root`](/learn/sdks/reference/generators-yml#root) to a file in an external git repository using the `git` sub-object. The CLI shallow-clones the repository at generation time, using your local git credential configuration. This is useful when spec files live in a private repo you don't want to copy.

  ```yaml title="generators.yml"
  api:
    specs:
      - openapi:
          git:
            repo: https://github.com/org/api-specs.git
            ref: main
            path: openapi/service.yml
  ```

## Multiple APIs

Fern supports two approaches for working with multiple API definitions. Both require an `apis` folder — this folder must use that exact name.

1. **Separate SDKs for each API** - Each API generates its own independent set of SDK packages (e.g., `@company/user-api`, `@company/payments-api` or versioned like `@company/sdk-v1`, `@company/sdk-v2`)
2. **Combined SDKs from multiple APIs** - Multiple APIs merge into a single SDK package with optional namespacing (e.g., `client.users`, `client.payments` or versioned like `client.v1`, `client.v2`)

### Separate SDKs for each API

Use this approach when each API should generate its own independent set of SDKs. This works for both distinct APIs (e.g., `user-api` and `payments-api`) and versioned APIs where you want each version to be independently installable (e.g., `@company/sdk-v1`, `@company/sdk-v2`).

#### Place each API in its own directory

Place each API or version of an API into a separate subfolder of `fern/apis/`:

#### Multiple distinct APIs

#### Multiple versioned APIs

#### Configure generators.yml for each API

Each API directory contains its own `generators.yml` file that references the spec in the same folder:

```yaml title="generators.yml"
api:
  specs:
    - openapi: openapi.yml # Spec file in the same folder
groups:
  # SDK generator configuration
```

### Combined SDKs from multiple APIs

#### Enterprise feature

This feature is available only for the [Enterprise plan](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).

Use this approach when you want to merge multiple APIs into a single SDK package, with optional namespacing to organize them. This works for both distinct APIs and versioned APIs, though it increases package size as all APIs are bundled together.

For versioned APIs, namespacing lets you access different versions like `client.v1` and `client.v2` within the same package.

#### Place each API in separate subfolders

Place each API into a separate subfolder of `fern/apis/`:

#### Multiple distinct APIs

#### Multiple versioned APIs

#### List all APIs in a single generators.yml

List all APIs in a single `generators.yml`:

```yaml title="generators.yml"
api:
  specs:
    - openapi: user-api/openapi.yml
    - openapi: payments-api/openapi.yml
groups:
  # SDK generator configuration
```

#### Add namespaces (optional)

Add [`namespace`](/learn/sdks/reference/generators-yml#namespace) to handle overlapping schema names between APIs or to organize different API versions:

#### Distinct APIs

```yaml title="generators.yml" {4}
api:
  specs:
    - openapi: apis/user-api/openapi.yml
    - namespace: payments
      openapi: apis/payments-api/openapi.yml
groups:
  # SDK generator configuration
```

#### Versioned APIs

List all API versions in a single `generators.yml` with namespaces:

```yaml title="generators.yml" {3, 5}
api:
  specs:
    - namespace: v1
      openapi: apis/v1/openapi.yml
    - namespace: v2
      openapi: apis/v2/openapi.yml
groups:
  # SDK generator configuration
```