# What is a Monorepo?
Source: https://speakeasy.com/docs/sdks/guides/creating-a-monorepo

import { Callout } from "@/mdx/components";


<Callout title="Warning" type="warning">
This section outlines an advanced setup process that may not be suitable for all users. For most use cases, we recommend adopting the simpler approach of a single SDK per GitHub repository. To setup a single SDK per Github see our [SDK quickstart](/docs/sdks/create-client-sdks).
</Callout>



A monorepo is a unified repository containing multiple SDKs, each corresponding to a unique OpenAPI specification. This approach offers a centralized location for discovering available SDKs while allowing for the independent download and management of each SDK as needed. Each SDK resides in its own subfolder, and can be made complete with individual GitHub workflows for regeneration and release processes.


## Repository Structure

The monorepo's structure is designed for scalability and easy navigation. In our example, we will discuss two SDKs: ServiceA and ServiceB, each found in their respective subfolders. The typical structure of such a monorepo is as follows:

```yaml
.github/workflows/
 - serviceA_generate.yaml # Github Workflow for generating the ServiceA SDK, generated by speakeasy cli
 - serviceA_release.yaml # Github Workflow for releasing and publishing the ServiceA SDK, generated by speakeasy cli
 - serviceB_generate.yaml # Github Workflow for generating the ServiceB SDK, generated by speakeasy cli
 - serviceB_release.yaml # Github Workflow for releasing and publishing the ServiceB SDK, generated by speakeasy cli
.speakeasy/workflow.yaml # Speakeasy workflow file that dictates mapping of sources (eg: openapi docs) and targets (eg: language sdks) to generate
serviceA/
 - gen.yaml # Generation config for the ServiceA SDK
serviceB/
 - gen.yaml # Generation config for the ServiceB SDK
 ```
 This structure can be expanded to accommodate any number of SDKs.

## Creating Your SDK Monorepo

You have two options for creating your SDK monorepo with Speakeasy and GitHub: starting from a template or building from scratch. For the purpose of this guide, we will use an example with two APIs, one for `lending` and one for `accounting`.

### Option 1: Use a Template
Start by cloning the [`template-sdk-monorepo` repository](https://github.com/speakeasy-sdks/template-sdk-monorepo?tab=readme-ov-file) using the "Use template" button on GitHub, and name it as you see fit.

### Option 2: Build from Scratch
1. Create a new repository on GitHub and clone it down locally with `git clone <repo-url>`.
2. Mimic the directory structure shown above. This can be achieved easily by following the interactive CLI commands below

a. Install Speakeasy CLI

b. Use quickstart to boostrap the repository. 
  
  This will create the necessary directories and files for you to start generating SDKs.

  ```bash
  speakeasy quickstart
  ```

  When prompted make sure to choose a sub directory rather than the root of your directory for generating the first target. We will add more targets in the following steps.

c. Configure your sources
  
  ```bash
  speakeasy configure sources
  ```
  For each source reference a local or remote OpenAPI document. Optionally add in an overlay if needed. Each source you configure here will be used 
  to point towards a generation target in the following step. 

 ![Screenshot of configuring sources for monorepo.](/assets/guides/monorepo-step-2c.png)

d. Configure your targets 

  For each target referenced a local or remote OpenAPI document. Optionally add in an overlay if needed. For ever target make sure to choose a 
  a language, a source and a subdirectory to generate the target in. In the provided example `accounting` and `lending` are two sub directories in which we'll generate two different targets for two different sources.

  ```bash
  speakeasy configure targets
  ```

 ![Screenshot of configuring targets for monorepo.](/assets/guides/monorepo-step-2d.png)

#### Final Speakeasy Workflow

The final speakeasy workflow file will look like the following

```yaml
workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
    accounting:
        inputs:
            - location: /path/to/accounting/openapi.yaml
    lending:
        inputs:
            - location: /path/to/lending/openapi.yaml
targets:
    accounting-ts:
        target: typescript
        source: accounting
        output: ./accounting
    lending-ts:
        target: typescript
        source: lending
        output: ./lending
```


#### Setup Github Release and Publishing Workflows

Finally if you want your SDKs to be regenerated and published in their Github repos setup the workflow files needed for remote generation and publishing. The CLI can help you set up these files with: 

```bash
speakesy configure publishing
```

Follow the prompts to setup your secrets in Github Action Secrets. Push up the repo to your remote location and watch everything spin!

### Configure Generation

Edit the `gen.yaml` file in the root of each SDK's subfolder. This file dictates the generator settings, including package name, class names, parameter inlining, and other preferences. For complete documentation on all the available publishing configurations, see [here](/docs/speakeasy-reference/generation/gen-yaml).

## Generate SDKs

### Locally

Simply run `speakeasy run` and select the SDKs you wish to regenerate. Use `speakaesy run --force` if there are no OpenAPI document changes.

 ![Screenshot of running all targets for monorepo.](/assets/guides/monorepo-step-run.png)

### Github

To manually trigger SDK generation:
1. Navigate to the Actions tab in your GitHub repository.
2. Select the generation workflow for the SDK you wish to generate.
3. Click "Run workflow" to start the generation process. Check mark the "Force" input option if there are no OpenAPI document changes.

## Verify your SDK

After generation, review the SDK to ensure it aligns with your requirements.