fern generate
You can run the fern compiler using the Fern CLI:
fern generate --group <group name>
TL;DR: generators.yml
controls what Fern will generate for you.
fern generate
validates your API and runs generators in the cloud
in isolated, containerized environments. You can view the list of available
generators here.
A modular compiler
Unlike most compilers, the Fern compiler does not produce a single output. Here are some examples of what the Fern compiler can output:
- A TypeScript SDK
- FastAPI boilerplate
- A Postman Collection
- An OpenAPI spec
To support the long and growing list of outputs, we’ve built the Fern Compiler to be modular. The core compiler is responsible for parsing and validating your Fern Definition, and producing the intermediate representation.
The remaining work is handled by generators. A Fern generator is a program that takes in an intermediate representation and outputs… something. Generators can be written in any language.
You specify which generators you want the compiler to run using the special file
generators.yml
. You can view the list of available generators here.
fern/
├─ fern.config.json
└─ api/
├─ generators.yml # <---
└─ definition/
├─ api.yml
└─ imdb.yml
generators.yml
Check out a real example
of generators.yml
.
In generators.yml
, you separate generators into groups.
groups:
# we run the FastAPI generator for server-side development
server:
generators:
- name: fernapi/fern-fastapi-server
version: 0.0.33
output:
location: local-file-system
path: ../../app/fern/server
# on every commit into the main branch, we generate SDKs for internal use
internal:
generators:
- name: fernapi/fern-typescript-node-sdk
version: 0.0.249
output:
location: npm
package-name: "@fern-api/plantstore"
token: ${NPM_TOKEN}
- name: fernapi/fern-java-sdk
version: 0.0.125
output:
location: maven
coordinate: io.github.fern-api:plantstore
username: ${MAVEN_USERNAME}
password: ${MAVEN_PASSWORD}
# when we release, we publish our external-facing SDKs
external:
generators:
- name: fernapi/fern-typescript-node-sdk
version: 0.0.249
github:
repository: my-org/node-sdk
You can run the fern compiler for a particular group using the Fern CLI:
fern generate --group <group name>
This validates your API and runs generators in the cloud in isolated, containerized environments.
You can also specify a default-group
in generators.yml
:
default-group: server
groups:
server: ...
Then, you can just run fern generate
to run the server
generator(s).
Generator schema
In this section, we’ll detail the different properties you need to include for a generator.
Name
Each generator has a unique name, e.g. fernapi/fern-typescript-node-sdk
.
groups:
external:
generators:
- name: fernapi/fern-typescript-node-sdk # <---
Version
You must specify which version of the generator you want to use. This helps ensure consistent builds.
groups:
external:
generators:
- name: fernapi/fern-typescript-node-sdk
version: 0.0.249 # <---
Configuration
Some generators allow for custom configuration, which you can specify using the optional config
key.
groups:
external:
- name: fernapi/fern-openapi
version: 0.0.11-4-g1c29f6c
github:
repository: fern-api/plantstore-openapi
+ config:
+ format: yaml
Output locations
You can optionally specify an location for the generated output. There are currently five supported output locations:
- npm registry
- Maven repository
- PyPI registry
- postman.com collection
- local filesystem output
npm registry
For generators that output a TypeScript/JavaScript package, you can publish the generated code directly to npm.
groups:
external:
generators:
- name: fernapi/fern-typescript-node-sdk
version: 0.0.249
output: # <---
location: npm
package-name: your-package-name
token: ${NPM_TOKEN}
By default, Fern publishes to npmjs.com. You can
override the registry using the url
key.
groups:
external:
generators:
- name: fernapi/fern-typescript-node-sdk
version: 0.0.249
output:
location: npm
package-name: your-package-name
token: ${NPM_TOKEN}
+ url: your-npm-registry.com
Maven repository
For generators that output a Java package, you can publish the generated code to a Maven repository.
groups:
external:
generators:
- name: fernapi/fern-java-sdk
version: 0.0.125
output: # <---
location: maven
coordinate: com.your-coordinate
username: ${MAVEN_USERNAME}
password: ${MAVEN_PASSWORD}
By default, Fern publishes to Maven Central. You can
override the registry using the url
key.
groups:
external:
generators:
- name: fernapi/fern-java-sdk
version: 0.0.125
output:
location: maven
coordinate: com.your-coordinate
username: ${MAVEN_USERNAME}
password: ${MAVEN_PASSWORD}
+ url: your-maven-repo.com
PyPI registry
For generators that output a Python package, you can publish the generated code directly to PyPI.
groups:
external:
generators:
- name: fernapi/fern-python-sdk
version: 0.1.0
output: # <---
location: pypi
package-name: your-package-name
token: ${PYPI_TOKEN}
By default, Fern publishes to pypi.org. You can
override the registry using the url
key.
groups:
external:
generators:
- name: fernapi/fern-python-sdk
version: 0.1.0
output:
location: pypi
package-name: your-package-name
+ username: your-username
+ password: ${PYPI_PASSWORD}
+ url: your-pypi.com
postman.com collection
The Postman generator can publish directly to your postman.com workspace.
groups:
external:
generators:
- name: fernapi/fern-postman
version: 0.0.31
output: # <---
location: postman
api-key: ${POSTMAN_API_KEY}
workspace-id: ${POSTMAN_WORKSPACE_ID}
To find your workspace ID, select the ⓘ icon in the top right of the workspace view.
Local filesystem output
You can always output the generated files to disk. This is helpful for local development, or for when you want to quickly introspect the generated files.
groups:
server:
generators:
- name: fernapi/fern-fastapi-server
version: 0.0.33
output: # <---
location: local-file-system
path: ../../app/fern/server
GitHub publishing
Fern can publish the generator’s output to a GitHub repo. It can be useful to have a dedicated repo for an output to track issues and its history over time.
For an example, check out Flipt’s Node.js SDK repo.
When you run the compiler with fern generate
, Fern will re-generate the Github
repo and push to the main
branch.
groups:
external:
generators:
- name: fernapi/fern-typescript-node-sdk
version: 0.0.249
github: # <---
repository: my-org/node-sdk
Combining with output
You can combine the output
and github
options. If you do, the generated
GitHub repo will include a GitHub workflow that publishes the source code to
its output destination.
For an example, check out Flipt’s GitHub workflow.
groups:
external:
generators:
- name: fernapi/fern-typescript-node-sdk
version: 0.0.249
+ output:
+ location: npm
+ package-name: your-package-name
+ token: ${NPM_TOKEN}
github:
repository: my-org/node-sdk
When you run the compiler with fern generate
, Fern will:
- Re-generate the Github repo and push to the
main
branch - Tag a release on the generated repo. This will trigger the GitHub workflow to publish to the output location (e.g. npm)
.fernignore
When you run the compiler with fern generate
, Fern will re-generate the entire
repo and delete any files it doesn’t recognize.
If you’d like for Fern to ignore certain files, use .fernignore
. This is
simlar to .gitignore
. Any files you list here will be ignored by Fern.
For an example, check out Flipt’s .fernignore.
Tip: it’s common to list README.md
in your .fernignore
so that Fern doesn’t wipe it out.