Contributing

Thanks for being here! This monorepo contains Fern's documentation, the Fern CLI, the Fern Definition, the OpenAPI importer, as well as all of our generators.

Fern is open source, but many of the people working on it do so as their day job. As a potential contributor, your changes and ideas are welcome, but we can't guarantee that they will be prioritized nor reviewed in a timely manner (if ever). With that said, we generally encourage users to start with a GitHub issue to discuss a feature or fix before writing any code. You're still welcome to include a patch as a proof-of-concept, but please do not be offended if we rewrite your patch from scratch.

Like all open-source projects, Fern's resources are limited. If your patch isn’t a top priority, it may not receive the attention you expect.

Setup

The Fern repo is primarily written in TypeScript and relies on PnPm for package management.

Once you have cloned or forked the repository, run through the steps below.

Step 1: Install dependencies

pnpm install

Step 2: Compile

To compile all the packages in this monorepo, run pnpm compile.

To compile a single package, filter to the relevant package: pnpm --filter @fern-api/openapi-parser compile.

Step 3: Testing

This repo contains both unit tests and integration (end-to-end) tests.

To run all the unit tests: pnpm test.

To run unit tests for a single package: pnpm --filter @fern-api/openapi-parser test

To run the integration tests: pnpm test:ete.

Many of our tests rely on snapshot testing. To rewrite snapshots, use pnpm test:update or pnpm test:ete:update.

Debugging

For debugging TypeScript code in tests, use the debug compilation and test scripts:

Compile for debugging: pnpm compile:debug
- Required for all debug workflows
- Uses --sourceMap flag to generate source maps for proper TypeScript debugging
- Slower than standard compilation, which is why source maps are disabled by default
Run tests with debugger: pnpm test:debug [test-file-name]
- Starts tests with Node.js debugger enabled
- Optionally specify a test file name to run only that test
- Manually attach VS Code debugger by opening Command Palette (Cmd+Shift+P) and selecting "Debug: Attach to Node Process"

Limitations: Debug scripts only work with vitest tests. Some -- but not all -- of the workflows they won't work with:

Local Fern CLI builds (compiled to single executable CJS file)
Generators (run in Docker containers, not all written in TypeScript)

Repository Architecture

Below we talk through the large components of this monorepo and how to contribute to each one.

Documentation

Fern's documentation is hosted live at the URL https://buildwithfern.com/learn. We appreciate any help we can get that makes our documentation more digestible.

If you find gaps within our documentation, please open an issue

Editing Documentation

Our documentation is powered by Fern's Docs product. All of the configuration for the docs lives in docs.yml.

To edit the docs, you can modify docs.yml or any of the markdown that it references.

To validate that the docs, run:

fern check

To preview the documentation, run:

fern docs dev

Finally, when you make a PR to update the docs, a PR preview link will be generated which will allow you to test if your changes came out as intended. Here is a sample PR with a preview link.

Fern CLI

The Fern CLI lives in a directory called cli and the entrypoint is cli.ts.

Building the CLI from source

For testing purposes, you can build a local version of the CLI by running pnpm fern:build. This compiles and builds a CLI that communicates with our production cloud environment.

The CLI is outputted to packages/cli/cli/dist/prod/cli.cjs.

Once the CLI has been built, you can navigate to any fern folder and invoke it by running

FERN_NO_VERSION_REDIRECTION=true node /<path to fern git repo>/packages/cli/cli/dist/prod/cli.cjs <args>

Development CLI

To build a CLI that communicates with Fern's development cloud environment, run the command pnpm fern-dev:build.

Once the CLI has been built, you can navigate to any fern folder and invoke it by running

FERN_NO_VERSION_REDIRECTION=true node /<path to fern git repo>/packages/cli/cli/dist/dev/cli.cjs <args>

Generators

All of Fern's generators live in a directory called generators. This directory contains generators for several languages such as typescript, python, go.

Some of the generators are written in the language they generate (i.e. Python is written in python, Go is written in Go, and Java is written in Java). We are moving to a world where each generator will be written in TypeScript so that we can share more utilities and enforce a consistent structure in the generator.

Generator Testing

Note: Please make sure that the docker daemon is running before running commands below.

To test our generators we have built a CLI called seed.

Seed handles building the generators from source and running them against all of the test definitions that are present in the repository. Generated code is then stored in a directory named seed.

Each generator configures a seed.yml. For example, the TypeScript generator's configuration lives here.

Seed also handles running scripts against the generated code to make sure that the generated code compiles and works as intended. For example, in the TypeScript generator seed runs yarn install and yarn build to compile the source code.

To build seed, simply run

pnpm seed:build

Note: If you make any changes to the seed source code then you will need to rerun pnpm seed:build.

To run seed, you can use the command:

pnpm seed test [--generator <generator-id>] [--fixture <fixture-name>] [--skip-scripts] [--local]

Below are some examples of using the command.

For a single generator: pnpm seed test --generator python-sdk
For a single generator and test definition: pnpm seed test --generator python-sdk --fixture file-download
For a single generator, test definition, and skipping scripts: pnpm seed test --generator python-sdk --fixture file-download --skip-scripts
For running the generator locally (not on docker): pnpm seed test --generator python-sdk --local

Running seed against a custom fern definition

It may be valuable to run seed on a particular Fern definition or OpenAPI spec. To do this, you can use the seed run command and point it at the fern folder:

pnpm seed run [--generator <generator-id>] [--path /path/to/fern/folder] [--output-path /path/for/sdk/output] [--audience <audience>]

Below are some examples of using the command.

Pointed at a fern folder: pnpm seed run --generator ts-sdk --path /Users/jdoe/fern --audience external
Pointed at a fern folder with an audience: pnpm seed run --generator ts-sdk --path /Users/jdoe/fern
Pointed at a fern folder with multiple apis: pnpm seed run --generator ts-sdk --path /Users/jdoe/fern/apis/<name-of-api>

## Feedback

If you have any feedback on what we could improve, please open an issue to discuss it!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!