SurfSense/apps/docs/documentation/local-development.mdx

---
title: "Local Development"
"og:title": "How to setup local development"
description: "A guide on how to run the codebase locally."
---

## Introduction

Next-Fast-Turbo 's codebase is set up in a monorepo (via [Turborepo](https://turbo.build/repo)) and is fully open-source.
Here's the monorepo structure:

```
apps
├── api
├── docs
├── web
packages
├── eslint-config
├── typescript-config
```

The `apps` directory contains the code for:

- `web`: The frontend of the Next-Fast-Turbo's application
- `api`: Next-Fast-Turbo's FastAPI backend - written in Python
- `docs`: Next-Fast-Turbo's documentation site

The `packages` directory contains the code for:

- `eslint-config`: ESLint configurations for Next-Fast-Turbo's codebase. Boilerplate code included as part of the [create Turbo](https://turbo.build/repo/docs/getting-started/create-new) command
- `typescript-config`: TypeScript configurations for Next-Fast-Turbo's codebase. Boilerplate code included as part of the [create Turbo](https://turbo.build/repo/docs/getting-started/create-new) command

## Running Next-Fast-Turbo
### Step 1: Local setup

<Steps>
  <Step title="Clone the repo">
    Clone the [Next-Fast-Turbo repo](https://github.com/cording12/next-fast-turbo.git).

    ```bash
    git clone https://github.com/cording12/next-fast-turbo.git app-name
    ```    

  </Step>
  <Step title="Install dependencies">    
    Change to the root directory of the cloned repository and install the dependencies using the following command:

    ```bash
    cd app-name
    pnpm install
    ```      
  </Step>    

  <Step title="Open code-workspace">
    It is recommended to use the pre-configured Workspace stored in the `.vscode` folder at the project root.

    Navigate to `app-name/.vscode/` and double click `next-fast-turbo.code-workspace` to open in VS Code, or, in VS Code navigate to **File** and then **Open Workspace from File**.

    <Tip>You can rename this to match your project name. The extension, `code-workspace`, must stay the same, but it can be changed to `app-name.code-workspace`</Tip>
  </Step>
</Steps>

### Step 2: Python setup
<Note>
  In a monorepo, VS Code sometimes uses the wrong Python interpreter, leading to **module not found** errors. You can open the `api` folder in its own VS Code window, but using
  the pre-configured Workspace is recommended. 
</Note>
While working on the Python backend, ensure that your terminal is activated in the correct folder. From the root, run the following command to change to the `api` directory:

```bash
cd apps/api
```

<Steps>
  <Step title="Create a virtual environment">
    Create a virtual environment in the `api` directory:

    <CodeGroup>
    ```bash Poetry
    poetry install
    ```

    ```bash Pip
    python -m venv .venv
    ```
    </CodeGroup>

  <Tip>
    If you're using Poetry, you could receive an error noting incorrect format of the `poetry.lock` file. This is a version mismatch between the version installed and the version used to generate the lock file. You can fix this by deleting the `poetry.lock` file
    and running `poetry install` again.
  </Tip>


  </Step>
  <Step title="Install dependencies (if not using Poetry)">    
    Run the following command to install the Python dependencies:

    ```bash
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Configure .env file">
    Create a `.env` file in the `api` directory and add the following environment variables:

    ```env
    DB_URL=supabase_url
    DB_API_KEY=supabase_api_key
    DB_EMAIl=email_address
    DB_PASSWORD=password
    ```

    These can be placeholder values for now, but you'll need to replace them with your actual Supabase credentials (covered in step 3).

  </Step>
</Steps>


### Step 3: Creating tables in Supabase
Next-Fast-Turbo uses [Supabase](https://supabase.com/) as the database for the backend. You'll need to create a new project in Supabase and then create the required tables. To get this example running, you need to only create two tables in Supabase.
<Steps>

  <Step title="Create an account and new project">
    Visit [Supabase](https://supabase.com/) and register an account. Once you're logged in, create a new project and give it a name.
    <Frame>
      <img src="/_images/supabase-project-create.png" />
    </Frame>
  </Step>

  <Step title="Add credentials to `.env`">
    While your project is building, copy the `Project API Key` and `URL` values and add these to the `.env` file in the `api` directory, as described in step 3 of the [Python setup](#step-2-python-setup).
    <Frame>
      <img src="/_images/supabase-credentials.png" />
    </Frame>
  </Step>
  
  <Step title="Create tables">
    The tables are seeded with the two `.csv` files located in the `api` root, but the tables must be created before seeding.
    
    From the dashboard, visit the `Table Editor` and click the `New table` button.     
    <Frame>
      <img src="/_images/supabase-new-table.png" />
    </Frame>

    Create the `users` and `spells` tables with columns that match their respective CSV columns. Below is how they are both configured:

    <Tabs>
      <Tab title="Users table">
        <Frame>
          <img src="/_images/supabase-create-user-table.png" />
        </Frame>
      </Tab>
      <Tab title="Spells table">
        <Frame>
          <img src="/_images/supabase-create-spells-table.png" />
        </Frame>
      </Tab>
    </Tabs>
    <Warning>
      RLS is set to disabled on these tables. Authentication with Supabase was not in the scope for this project, but you will want to configure this yourself for anything more than this simple example.
      You can read more about [RLS](https://supabase.com/docs/guides/auth/row-level-security) in the Supabase documentation.
    </Warning>
  </Step>

  <Step title="Upload CSV seed data">
    Once the tables are created, you can seed them with the data from the `.csv` files. From the `Table Editor`, click the `Insert` button and select the relevant `.csv` file to upload.
    <Frame>
      <img src="/_images/supabase-upload-csv.png" />
    </Frame>
  </Step>

</Steps>

### Step 4: Configure Turbo remote caching (optional)
Turborepo can use a technique known as [Remote Caching](https://turbo.build/repo/docs/core-concepts/remote-caching) to share cache artifacts across machines, enabling you to share build caches with your team and CI/CD pipelines.

By default, Turborepo will cache locally. To enable Remote Caching you will need an account with Vercel.

<Steps>
  <Step title="Login via Turborepo CLI">
    From the project root, run the command:
    ```bash    
    npx turbo login
    ```
    This will authenticate the Turborepo CLI with your [Vercel account](https://vercel.com/docs/concepts/personal-accounts/overview).
  </Step>
  <Step title="Link your Turborepo to your Remote Cache">
  Link your Turborepo to your Remote Cache by running the following command from the root of your Turborepo:
  ```bash
  npx turbo link
  ```
  </Step>
</Steps>

### Step 5: Running everything
To make the most of Turbo's monorepo structure, you can run the frontend, backend and documentation site simultaneously. From the root, run the following command:

```bash root
pnpm run dev
```
<Tip>You can still run each separately by running the task directly from the relevant `package.json` or by running the `pnpm run dev` command from a terminal activated in the desired target location</Tip>


## Working with a monorepo in VS Code

For a better development experience, you can use VS Code Workspaces for the monorepo. This will allow you to run tasks and debug the codebase from a single window, while keeping things more organised.

Furthermore, VS Code doesn't handle Python virtual environments particularly well when working within a monorepo. Running the `dev` command from the project root can make VS Code use your global Python installation, 
instead of the `.venv` created in the `api` root. By using a Workspace, this alleviates the problem. 

<Note>For a more detailed guide on setting up a monorepo in VS Code, check out the [official Multi-root Workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) documentation</Note>

### Step 1: Open the monorepo
In the `/.vscode/` directory, you'll find a `next-fast-turbo.code-workspace` file. Open this file in VS Code to open the monorepo Workspace.

<Tabs>
<Tab title="No code-workspace">
<Frame caption="Frontend (web) folder open without using the Workspace">
  <img src="/_images/no-workspace.png" />
</Frame>
</Tab>

<Tab title="With a code-workspace">
<Frame caption="Frontend (web) folder open with a Workspace">
  <img src="/_images/workspace.png" />
</Frame>
</Tab>
</Tabs>

### Step 2: Running tasks
VS Code will try to autodetect tasks from gulp, grunt, npm, and TypeScript project files across all folders in a workspace as well as search for tasks defined in tasks.json files. The location of tasks is indicated by a folder name suffix

<Frame caption="Workspace tasks">
  <img src="/_images/tasks.png" />
</Frame>

From the above example, you can see there are several configured tasks with the relevant folder name after the task name.

### Step 3: Debugging
With multi-root workspaces, VS Code searches across all folders for `launch.json` debug configuration files and displays them with the folder name as a suffix. 
Additionally VS Code will also display launch configurations defined in the workspace configuration file.

<Frame caption="Run and debug panel">
  <img src="/_images/run-and-debug.png" />
</Frame>

You can still create [launch configurations](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) for each individual package in the monorepo and they will populate in the dropdown list automatically.

#### Workspace launch configurations
If you want to create a Workspace level configuration with [compound launch](https://code.visualstudio.com/docs/editor/debugging#_compound-launch-configurations), you can edit the `next-fast-turbo.code-workspace` file and add the configurations you wish to launch.

<Tip>You can also edit the Workspace configuration file via the Command Palette\
(Windows: Ctrl + Shift + P) and searching for `open workspace config`</Tip>

A compound launch configuration can reference the individual launch configurations by name as long as the names are unique within the workspace, for example:

```json
{
  "launch": {
    "version": "0.2.0",
    "configurations": [],
    "compounds": [
      {
        "name": "Launch Frontend and Backend",
        "configurations": ["Next.js: Chrome", "Python: FastAPI"]
      }
    ]
  }
}
```

For a more detailed explanation, check out the [official documentation](https://code.visualstudio.com/docs/editor/multi-root-workspaces#_workspace-launch-configurations)

### Optional: Extensions
<AccordionGroup>
  <Accordion title="Python Envy">    
      Helps VS Code identify the correct Python virtual environment when installed in the working directory. This is especially useful when working with Python in a monorepo, as it can be difficult for VS Code to manage multiple virtual environments.

      [Python Envy](https://marketplace.visualstudio.com/items?itemName=teticio.python-envy)
  </Accordion>
  <Accordion title="Workspace Terminals (recommended)">
    <Frame caption="Workspace Terminals in VS Code">
      <img src="/_images/terminals.png" />
    </Frame>
      Terminal management in a monorepo can become cumbersome. This extension automatically creates a terminal in each of your monorepo's directories and names them accordingly. This will allow you to run commands and tasks from a terminal that's already set up in the correct directory.

      [Workspace Terminals](https://marketplace.visualstudio.com/items?itemName=joshx.workspace-terminals)
  </Accordion>
</AccordionGroup>


## Next Steps

<CardGroup cols={2}>
  <Card title="Turbo config" icon="code" href="configuration/turbo">
    Configuring Turbo for your monorepo
  </Card>
  <Card title="FastAPI config" icon="database" href="configuration/fastapi">
    Configuring FastAPI
  </Card>
  <Card title="Frontend config" icon="computer" href="configuration/nextjs">
    Configuring Next.js
  </Card>
  <Card title="Documentation config" icon="book" href="configuration/docs">
    Configuring Mintlify for documentation
  </Card>
</CardGroup>