diff --git a/fern/products/sdks/fern-folder.mdx b/fern/products/sdks/fern-folder.mdx index 4e750bf4f..11fed8040 100644 --- a/fern/products/sdks/fern-folder.mdx +++ b/fern/products/sdks/fern-folder.mdx @@ -30,24 +30,9 @@ in different languages and [augmenting them with custom code](/sdks/overview/cus {/* */} - ### Generate an SDK in your desired language - - - } href="/sdks/generators/typescript/quickstart"> - - } href="/sdks/generators/python/quickstart"> - - } href="/sdks/generators/go/quickstart"> - - } href="/sdks/generators/java/quickstart"> - - } href="/sdks/generators/csharp/quickstart"> - - } href="/sdks/generators/php/quickstart"> - - } href="/sdks/generators/php/quickstart"> - - + ### Set up GitHub + + Now, you're ready to [set up your GitHub repositories](/sdks/overview/github). ### Augment your SDK with custom code diff --git a/fern/products/sdks/github-setup.mdx b/fern/products/sdks/github-setup.mdx new file mode 100644 index 000000000..737154be9 --- /dev/null +++ b/fern/products/sdks/github-setup.mdx @@ -0,0 +1,109 @@ +--- +title: Structure your GitHub repositories +description: Set up GitHub repositories for your SDKs +--- + +Before generating SDKs with Fern, you'll need to 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. + + +## Structuring your top-level repository + +1. Identify or create a top-level GitHub repository where you want all of your + SDK and API code to live. +1. Install the [Fern GitHub App](https://github.com/apps/fern-api) on the + top-level repository and all SDK repositories. Select **Configure**, then + scroll down to **Repository Access**. Select **Only select repositories** and + in the dropdown select the repository for your SDK. Click **Save**. + +For example, your basic GitHub file structure should look something like this: + +``` +├─ company-repo # Top-level repo for all SDKs + ├─ fern/ + ├─ apis/ + ├─ sdks/ + └── generators.yml # Contains settings for all SDKs +``` +Your `generators.yml` file will contain a group for each of your SDKs. Each group points +to the GitHub repository for the relevant SDK. + +For example, the `group` for a TypeScript SDK might look like this: + +```yaml title="generators.yml" + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: 2.6.3 + github: + repository: your-organization/your-typescript-repo +``` + +For additional examples, see Cohere's [`generators.yml` +file](https://github.com/cohere-ai/cohere-developer-experience/blob/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern/apis/sdks/generators.yml) +and Vapi's [`generators.yml` +file](https://github.com/VapiAI/docs/blob/9c674c2b16ba03e864e26673c5290c88048c9a7a/fern/apis/api/generators.yml). + +You can also additionally configure the `github` section to whether Fern +should commit and release, create a pull request, or push code to a branch when +you make changes to your SDK code. See [GitHub +Configuration](/sdks/reference/generators-yml#github-configuration) for more +details. + +## Structuring SDK-specific repositories + +1. Create a new GitHub repository called `company-` (or something + similar) for each of your SDKs, if you haven't done so already. +1. Install the [Fern GitHub App](https://github.com/apps/fern-api) on the + top-level repository and all SDK repositories. Select **Configure**, then + scroll down to **Repository Access**. Select **Only select repositories** and + in the dropdown select the repository for your SDK. Click **Save**. + + +The repository structure for a specific SDK should look similar to this: + +```{6-11} +├─ company-repo # Top-level repo for all SDKs + ├─ fern/ + ├─ apis/ + ├─ sdks/ + └── generators.yml # Contains settings for all SDKs + ├─ typescript-sdk-repo # Repository for a TypeScript SDK + ├─ .github/workflows/ # Contains GitHub Actions for publishing to package repositories, etc. + ├─ scripts/ + ├─ src/ + ├─ tests/ + └── .fernignore # Lists files that Fern shouldn't modify + ├─ python-sdk-repo + └── go-sdk-repo +``` + +Fern generates most of the SDK files listed in this example repository (`scripts/`, `src/`, `tests`, +`.fernignore`, etc.), including any custom code you added. You have to manually set up `.github/workflows` to execute actions, like publishing SDK versions to a package repository. + +For additional examples, see Cohere's [Python SDK repository](https://github.com/cohere-ai/cohere-python) and [Vapi's TypeScript SDK repository](https://github.com/VapiAI/server-sdk-typescript). + +## Generate an SDK in your desired language + +Once you've set up your GitHub repository structure, you can proceed with generating SDKs in your desired languages. + + + } href="/sdks/generators/typescript/quickstart"> + + } href="/sdks/generators/python/quickstart"> + + } href="/sdks/generators/go/quickstart"> + + } href="/sdks/generators/java/quickstart"> + + } href="/sdks/generators/csharp/quickstart"> + + } href="/sdks/generators/php/quickstart"> + + } href="/sdks/generators/php/quickstart"> + + + + + diff --git a/fern/products/sdks/overview/typescript/assets/npm-token-secret.png b/fern/products/sdks/overview/typescript/assets/npm-token-secret.png new file mode 100644 index 000000000..b071b8df8 Binary files /dev/null and b/fern/products/sdks/overview/typescript/assets/npm-token-secret.png differ diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index 4605c4a4e..c06ccfc13 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -11,52 +11,28 @@ you'll have a versioned package published on npm. Versioned package published on npm - + + This page assumes that you have: -## Set up your GitHub integration + * An initialized `fern` folder on your local machine. See [Set up the `fern` + folder](/sdks/overview/quickstart). + * A GitHub repository for your TypeScript SDK. See [Set up your GitHub structure](/sdks/overview/github). + * A TypeScript generator group in `generators.yml`. See [TypeScript + Quickstart](quickstart#add-the-sdk-generator). - 1. Create a new GitHub repository called `company-typescript` (or something similar) for your SDK, if you haven't done so already. - 1. Install the [Fern GitHub App](https://github.com/apps/fern-api): Select **Configure**, then scroll down to **Repository Access**. Select **Only select repositories** and in the dropdown select the repository for your SDK. Click **Save**. - + ## Configure `generators.yml` - - - Navigate to your `generators.yml` on your local machine. Your `generators.yml` lives inside of your `fern` folder and contains all the configuration for your Fern generators. - - Add a new generator to `generators.yml`: - - - ```bash - fern add fern-typescript-sdk --group ts-sdk - ``` - - Once the command completes, you'll see a new group created in your `generators.yml`: - - ```yaml {3-9} - groups: - ... - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - output: - location: local-file-system - path: ../sdks/typescript - ``` - - - - Next, change the output location in `generators.yml` from `local-file-system` (the default) to `npm` to indicate that Fern should publish your package directly to the npm registry: + In the `group` for your TypeScript SDK, change the output location in from `local-file-system` (the default) to `npm` to indicate that Fern should publish your package directly to the npm registry: ```yaml {6-7} groups: - ts-sdk: + ts-sdk: # Group name for your TypeScript SDK generators: - name: fernapi/fern-typescript-sdk version: @@ -106,7 +82,7 @@ groups: - Add the path to your GitHub repository to `generators.yml`: + Add the path to your GitHub repository to `generators.yml`, if you haven't already: ```yaml {11-12} groups: @@ -118,7 +94,7 @@ groups: location: npm package-name: your-package-name config: - namespaceExport: your-client-name + namespaceExport: YourClientName github: repository: your-org/company-typescript ``` @@ -126,7 +102,7 @@ groups: -## Set up npm publishing authentication +## Generate an npm token @@ -184,6 +160,79 @@ groups: + + +## Configure npm authentication + + + + +Use [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) to automatically publish new SDK versions to npm when you push code changes. + + + + + + Open your Fern repository in GitHub. Click on the **Settings** tab in your repository. Then, under the **Security** section, open **Secrets and variables** > **Actions**. + + + Adding GitHub Repository Secret + + + You can also use the url `https://github.com//settings/secrets/actions`. + + + + + + 1. Select **New repository secret**. + 1. Name your secret `NPM_TOKEN`. + 1. Add the corresponding token you generated above. + 1. Click **Add secret**. + + + NPM_TOKEN secret + + + + + + + Change your workflow permissions to allow GitHub to run workflows: + + 1. Click on the **Settings** tab in your repository. + 1. Under the **Code and automation** section, navigate to **Actions** > **General**. + 1. Under **Actions permissions**, select **Allow all actions and reusable workflows**. + 1. **Save** your settings. Now GitHub can run the actions you configure. + + + + + Add `token: ${NPM_TOKEN}` to `generators.yml` to tell Fern to use the `NPM_TOKEN` environment variable (which you just configured in your GitHub repo) for authentication when publishing to the npm registry. + + ```yaml {9} + groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + output: + location: npm + package-name: name-of-your-package + token: ${NPM_TOKEN} + config: + namespaceExport: YourClientName + github: + repository: your-org/your-repository + ``` + + When you regenerate your release, Fern will automatically create a workflow in your repository called `.github/workflows/ci.yml` that will automatically publish your release to npm. For an example, see Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml) + + + + + + Add `token: ${NPM_TOKEN}` to `generators.yml` to tell Fern to use the `NPM_TOKEN` environment variable for authentication when publishing to the npm registry. @@ -199,20 +248,11 @@ groups: package-name: name-of-your-package token: ${NPM_TOKEN} config: - namespaceExport: your-client-name + namespaceExport: YourClientName github: repository: your-org/your-repository ``` - - - -## Release your SDK to NPM - - At this point, you're ready to generate a release for your SDK. - - - Set the `NPM_TOKEN` environment variable on your local machine: @@ -222,8 +262,13 @@ groups: ``` + + + + + - +## Release your SDK to npm Regenerate your SDK and publish it on npm: @@ -232,8 +277,4 @@ groups: ``` Local machine output will verify that the release is pushed to your repository and tagged with the version you specified. Log back into npm and - navigate to **Packages** to see your new release. - - - - \ No newline at end of file + navigate to **Packages** to see your new release. \ No newline at end of file diff --git a/fern/products/sdks/overview/typescript/quickstart.mdx b/fern/products/sdks/overview/typescript/quickstart.mdx index 58ede0763..a9a15e6e4 100644 --- a/fern/products/sdks/overview/typescript/quickstart.mdx +++ b/fern/products/sdks/overview/typescript/quickstart.mdx @@ -5,13 +5,19 @@ description: Get started quickly with the Fern TypeScript SDK. Generate a TypeScript SDK by following the instructions on this page. - + + This page assumes that you have: + + * An initialized `fern` folder on your local machine. See [Set up the `fern` + folder](/sdks/overview/quickstart). + * A GitHub repository for your TypeScript SDK. See [Set up your GitHub repositories](/sdks/overview/github). + -### Add the SDK generator +## Add the SDK generator Run the following command to add the TypeScript SDK generator to `generators.yml`: @@ -37,7 +43,7 @@ This command adds the following `group` to `generators.yml`: location: local-file-system path: ../sdks/typescript ``` -### Generate the SDK +## Generate the SDK Run the following command to generate your SDK: diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml index 3206477d3..c771d7522 100644 --- a/fern/products/sdks/sdks.yml +++ b/fern/products/sdks/sdks.yml @@ -7,6 +7,9 @@ navigation: - page: Quickstart path: ./fern-folder.mdx slug: quickstart + - page: GitHub Setup + path: ./github-setup.mdx + slug: github - page: Adding Custom Code path: ./custom-code.mdx slug: custom-code