Local Development

A guide on how to run the codebase locally.

Introduction

Next-Fast-Turbo ‘s codebase is set up in a monorepo (via Turborepo) 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 command
• typescript-config: TypeScript configurations for Next-Fast-Turbo’s codebase. Boilerplate code included as part of the create Turbo command

Running Next-Fast-Turbo

Step 1: Local setup

1. Clone the repo

   Clone the Next-Fast-Turbo repo.

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

2. Install dependencies

   Change to the root directory of the cloned repository and install the dependencies using the following command:

   cd app-name
   pnpm install
   

3. 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.

   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

Step 2: Python setup

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.

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:

cd apps/api

1. Create a virtual environment

   Create a virtual environment in the api directory:

   Poetry

   poetry install
   

   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.

2. Install dependencies (if not using Poetry)

   Run the following command to install the Python dependencies:

   pip install -r requirements.txt
   

3. Configure .env file

   Create a .env file in the api directory and add the following environment variables:

   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 3: Creating tables in Supabase

Next-Fast-Turbo uses Supabase 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.

1. Create an account and new project

   Visit Supabase and register an account. Once you’re logged in, create a new project and give it a name.

   
2. 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.

   
3. 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.

   

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

   Users table

   

   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 in the Supabase documentation.

4. 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.

   

Step 4: Configure Turbo remote caching (optional)

Turborepo can use a technique known as 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.

1. Login via Turborepo CLI

   From the project root, run the command:

   npx turbo login
   

   This will authenticate the Turborepo CLI with your Vercel account.

2. 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:

   npx turbo link
   

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:

root

pnpm run dev

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

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.

For a more detailed guide on setting up a monorepo in VS Code, check out the official Multi-root Workspaces documentation

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.

No code-workspace

Frontend (web) folder open without using the Workspace

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

Workspace tasks

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.

Run and debug panel

You can still create 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, you can edit the next-fast-turbo.code-workspace file and add the configurations you wish to launch.

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

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

{
  "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

Optional: Extensions

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

Workspace Terminals (recommended)

Workspace Terminals in VS Code

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

Next Steps

Turbo config

Configuring Turbo for your monorepo

FastAPI config

Configuring FastAPI

Frontend config

Configuring Next.js

Documentation config

Configuring Mintlify for documentation