Setting Up a Robust Supabase Local Development Environment

Setting up a robust local development environment is crucial for efficient and effective software development, and Supabase is no exception. A solid Supabase local dev setup allows developers to build, test, and iterate on their applications without relying on a live production environment. This article provides a comprehensive guide to establishing a local Supabase development environment, drawing from various sources to offer a well-rounded approach.

Initial Setup for Supabase Local Development

To begin your Supabase local dev setup, you need to ensure you have the necessary tools installed. This primarily includes Docker, the Supabase CLI, and potentially Git for version control.

Installing Docker

Docker is essential for running Supabase's services locally. The installation process varies slightly depending on your operating system. For Windows, WSL 2.0 (Windows Subsystem for Linux) provides a suitable environment for Docker. While macOS can also run Docker, it might experience performance limitations due to its virtualization. Linux is technically the best option, but Windows 11 with WSL 2.0 offers a user-friendly experience with good performance. Regardless of your OS, ensure Docker Desktop is installed and running before proceeding.

Installing the Supabase CLI

The Supabase CLI is your primary tool for managing the local Supabase environment. The installation method depends on your operating system and preferred package manager.

• npm (Node.js): Use npm install supabase --save-dev then execute commands with npx supabase <command>.
• macOS (Homebrew): Use brew install supabase/tap/supabase.
• Windows (Scoop): First, add the bucket with scoop bucket add supabase https://github.com/supabase/scoop-bucket.git, then install with scoop install supabase.
• Linux (Homebrew): Use brew install supabase or download the appropriate package from the Releases page.

Once the CLI is installed, you can verify the version by running supabase -v in your terminal. Keeping the CLI up-to-date ensures compatibility with the latest Supabase features. Update the CLI with npm update supabase --save-dev (npm), brew upgrade supabase (macOS, Linux), or scoop update supabase (Windows). After updating, restart the local Supabase stack with supabase stop --no-backup followed by supabase start.

Initializing and Starting Your Supabase Project Locally

After installing the necessary tools, you can begin setting up your Supabase local dev setup.

Initializing the Project

Navigate to your project directory in the terminal, and run the command supabase init. This command creates a supabase directory in your project, which contains the configuration files needed for local development. It’s good practice to commit this supabase directory to your version control system.

Starting the Local Supabase Stack

To start the local Supabase services, run supabase start in your project directory. The first time you run this command, Docker will download the necessary images, which may take some time. Once started, the CLI will provide you with local credentials and the URL to access the Supabase Studio dashboard, usually http://localhost:54323.

Customizing Your Local Development Environment

With the basic setup complete, you can now customize your local environment further.

Configuring Email Templates

Supabase provides configurable email templates for various authentication flows. For local development, you can customize these templates by modifying the config.toml file within the supabase directory. You can specify the paths to your HTML email templates for different types of emails, such as invites or password resets.

For instance, to set up an invite email template, you would add the following configuration to your config.toml:

[auth.email.template.invite]
subject = "You are invited to Acme Inc"
content_path = "./supabase/templates/invite.html"

Similarly, you can configure templates for password recovery, email confirmations, and other authentication-related emails. The config.toml file also allows you to set up SMTP settings for testing emails locally. For local testing, Supabase uses Inbucket, which is automatically available at http://localhost:54324 when you run supabase start.

Managing Configuration and Secrets

The config.toml file is the central place to manage your local Supabase configuration. It allows you to configure various aspects of your local Supabase environment, including API settings, database parameters, and external OAuth providers. You can reference environment variables within config.toml using the env() function. This is particularly useful for sensitive information such as API keys and secrets, which should not be committed directly to your version control system. Create a .env file in the root of your project directory to store these variables.

For instance, to enable GitHub authentication, you might add the following to your config.toml and .env file:

[auth.external.github]
enabled = true
client_id = "env(GITHUB_CLIENT_ID)"
secret = "env(GITHUB_SECRET)"
redirect_uri = "http://localhost:54321/auth/v1/callback"

GITHUB_CLIENT_ID="your_github_client_id"
GITHUB_SECRET="your_github_client_secret"

Remember to exclude the .env file from your git repository by adding it to your .gitignore file.

Database Migrations and Seeding

Managing database changes through migrations is essential for a consistent development workflow. Supabase CLI provides commands to create, apply, and manage migrations. You can create a new migration using the command supabase migration new <migration_name>. Supabase also provides a supabase db diff --schema public command to see differences between your local database and the schema. This is useful when you make changes via the Supabase Studio and need to capture those changes as a migration.

After creating a migration, you can add the necessary SQL to modify your database schema. To apply migrations and reset your database to a known state, use the command supabase db reset. This command will re-run all migrations and apply any seed data you have specified in the supabase/seed.sql file.

Populate your local database using a seed file, which contains SQL statements to insert initial data. Create a supabase/seed.sql file and add the necessary INSERT statements. Supabase will automatically execute this file whenever you run supabase start or supabase db reset. You can also use supabase db dump to backup your database.

Working with Supabase Storage

Supabase Storage allows you to store and manage files. In your local development environment, Storage will work with a local file system. However, the Supabase Studio UI does not directly support Storage in a local development environment, so you will need to configure the RLS (Row Level Security) on buckets and objects using SQL. You can configure storage buckets via the config.toml file by specifying the file size limit, allowed mime types, and the local directory to upload objects to. For example, to configure a bucket named images, you would add the following to your config.toml:

[storage.buckets.images]
public = false
file_size_limit = "50MiB"
allowed_mime_types = ["image/png", "image/jpeg"]
objects_path = "./images"

Credit: blog.logrocket.com

Testing Your Local Setup

Testing the Supabase local dev setup ensures that your application behaves as expected before deploying to production.

Local Email Testing

Supabase utilizes Inbucket for local email testing. When you run supabase start, Inbucket is automatically accessible at http://localhost:54324. This allows you to view emails sent from your application locally. You will need to configure your project to use Inbucket by setting the SMTP settings in your project's supabase/config.toml.

Local API Access

You can access your local Supabase API by using the supabase status command to retrieve the local API endpoint. This allows you to verify that your API is correctly configured and is returning the data you expect. For local file storage, the endpoint will be similar to http://127.0.0.1:54321/storage/v1/s3, which you will use with the tus-js-client library.

Supabase Studio

The Supabase Studio dashboard is accessible at http://localhost:54323. This is where you can manage your database, authentication, storage, and other features. You can use the Studio to create tables, modify schema, and explore the data in your local database.

Deploying Your Application

Once you have thoroughly tested your application locally, you can deploy it to your live Supabase project. This involves linking your local project to your remote Supabase project and pushing any database changes.

Linking your local project to your remote Supabase project

First, log in to the Supabase CLI using supabase login. Then, link your local project to your remote project using the command supabase link --project-ref <project-id>. You can find the <project-id> in your Supabase dashboard URL.

Pushing Database Changes

After linking your project, you can use the supabase db pull command to capture any changes from your remote database that you may have made outside of your local development. Then you can apply your local migrations to your remote database using the command supabase db push. You can also deploy your local Edge Functions with supabase functions deploy <function_name>.

Additional Tips and Considerations

• Regularly update your Supabase CLI to benefit from the latest features and bug fixes.
• Utilize environment variables for sensitive information and avoid committing them to your version control system.
• Leverage database migrations to track schema changes and ensure a consistent development environment across your team.
• Use the Supabase Studio to explore and modify your local database.
• Test your application thoroughly before deploying to a live environment.

By following these steps, you can establish a robust Supabase local dev setup, enabling you to build and iterate on your applications efficiently. This approach will help you streamline your development process, improve your application's reliability, and reduce the potential for issues in production.