Vibe Coding Starter Kit Guide

This guide walks you through setting up and using the Vibe Coding Starter Kit, a full-stack template for building apps with file uploads and object storage, backed by Backblaze B2 Cloud Storage. By the end, you will have a working dashboard running locally with file upload, browsing, and storage management already wired up.

This guide describes Vibe Coding Starter Kit v1.0.0. For other versions, see the tagged releases in the GitHub repository.

Prerequisites

Before you start, make sure you have the following prerequisites in place.

• Backblaze B2 enabled on your account

• A Backblaze B2 bucket, noting the endpoint URL

• A Backblaze B2 application key scoped to the bucket you just created

• Node.js 20 or later

• pnpm 9 or later

• Python 3.12 or later

• macOS, Linux, or WSL2 on Windows (Native Windows is not supported.)

Create a Project from the Template

The repo is a GitHub template, so you can create a clean copy without any upstream history.

Option A: Use the GitHub template (recommended)

1. Go to github.com/backblaze-b2-samples/vibe-coding-starter-kit.

2. Click Use this template, and name your new repo.

3. Clone your new repo locally:

git clone https://github.com/yourorg/my-app.git
cd my-app

Option B: Clone and reinitialize

To skip GitHub's template flow, clone the repo directly and reset its git history:

git clone https://github.com/backblaze-b2-samples/vibe-coding-starter-kit.git my-app
cd my-app
rm -rf .git
git init
git add .
git commit -m "Initial commit from vibe-coding-starter-kit"

Install Dependencies

The project uses pnpm workspaces to manage both the frontend and backend from a single root. One command from the project root sets up everything, including the Python backend:

pnpm run setup

The command installs the workspace dependencies, creates the API’s Python virtual environment, and copies .env.example to .env if the file does not already exist. You can safely run the command again because it does not overwrite an existing .env file.

Run the script with pnpm run. In versions earlier than pnpm 11, setup and doctor are built-in pnpm commands, so commands such as pnpm setup run pnpm’s built-in command instead of the corresponding project script.

Configure Environment Variables

1. A single .env file at the project root supplies credentials to both the API and the web console. Setup already created it; if it is missing, copy the example file:

   cp .env.example .env

2. Open .env and replace the placeholder values with your real credentials. Replace us-west-004 with the region shown in your bucket's endpoint URL if it differs:

   # .env
   B2_ENDPOINT=https://s3.us-west-004.backblazeb2.com
   B2_KEY_ID=your-key-id
   B2_APPLICATION_KEY=your-application-key
   B2_BUCKET_NAME=your-bucket-name

Run the App

Start both the frontend and backend with a single command:

pnpm dev

pnpm dev runs a preflight check (pnpm run doctor) before starting the servers. That check catches the most common setup problems: wrong Node or Python version, a missing virtual environment, an unfilled .env, or ports already in use. If something is misconfigured, it tells you exactly what to fix. You can also run it on its own at any time:

pnpm run doctor

You can access each service at:

• Frontend: localhost:3000

• API: localhost:8000

• API health check: localhost:8000/health

Upload a file from the dashboard. If it lands in your bucket, the setup is complete.

Included Features

These features are included and working when you run the app.

Dashboard shows storage stats, an upload activity chart, and a table of recent uploads.

File browser lists all files in your bucket in a tree view. From there you can preview, download, or delete individual files.

File upload supports drag-and-drop with real-time progress tracking. Images and PDFs get metadata extracted automatically (dimensions, EXIF data, page count, checksums).

Design system is available at localhost:3000/design as a live preview of the component library and tokens used throughout the UI.

Project Structure

The project is organized as a monorepo with three main areas:

apps/web/          Next.js frontend (TypeScript, Tailwind v4, shadcn/ui)
services/api/      FastAPI backend (Python, boto3, Pydantic v2)
packages/shared/   Shared TypeScript type definitions

Useful Commands

These commands all run from the project root.

API Endpoints

The FastAPI backend exposes the following REST endpoints. All file keys are validated against a prefix allowlist before any operation runs.

Uploads do not pass through the API. Instead, the browser requests a presigned URL, uploads the file directly to Backblaze B2, and then calls the verification endpoint.

Additional routes provide dashboard statistics and file previews. For a complete list of routes, see the interactive API documentation at localhost:8000/docs.

Deploy to Vercel

Vercel is the simplest deployment option because the web app and API deploy as a single project with the same origin. The frontend runs at /, and the API runs under /api. There is no CORS to configure between them and no second URL to wire into the frontend.

1. Use the deploy button in the repository README, or create a Vercel project from your copy of the repository.

2. Add B2_KEY_ID, B2_APPLICATION_KEY, B2_ENDPOINT, and B2_BUCKET_NAME when Vercel prompts you for environment variables.

3. Click Deploy.

Files upload directly from the browser to Backblaze B2, so Vercel’s 4.5 MB request body limit does not apply. However, because the browser connects directly to Backblaze B2, the bucket must allow requests from your deployed web origin. See Allow Your Web Domain on the Bucket.

Deploy to Railway

Use Railway if you want to deploy and scale the frontend and backend independently while keeping them in the same repository.

1. Create a new project in Railway.

2. Add two services, both pointing to your repo.

Each service includes a configuration file at the default path Railway checks relative to the service’s root directory. After you set the root directories as shown below, Railway reads the build command, start command, and health check from these files. Leave the Build Command and Start Command fields in the Railway dashboard empty.

Web service (Next.js)

Set the web service’s root directory to the repository root. The web service depends on the shared workspace package in packages/shared, so setting the root directory to apps/web causes the build to fail.

API service (FastAPI)

After both services are created, set environment variables in each service's settings.

API service environment variables

Web service environment variables

Allow Your Web Domain on the Bucket

CORS must be configured for both the API and the Backblaze B2 bucket. API_CORS_ORIGINS allows your web application to access the API, but it does not control direct uploads to Backblaze B2. Because the browser uploads files directly to B2, the bucket must also allow your deployed web origin to use the PUT method and the content-type header.

Without this bucket rule, the browser’s CORS preflight request fails and the upload does not begin. Meanwhile, /health can report a healthy connection and file listing can continue to work, which can make the cause difficult to identify.

Run the following command once for each deployed origin. It adds the origin to the bucket’s existing CORS rules without replacing them:

python services/api/scripts/setup_b2_cors.py --origin https://<your-web-domain> --apply

You might not encounter this issue during local development because development buckets often already allow requests from localhost.

Troubleshooting

If something is not working after setup, here are the most common causes.

B2 authentication failed

Verify that your bucket name, endpoint, key ID, application key, and key permissions are all correct. The application key must have access to the bucket you specified.

Python virtual environment not found

From the project root, rerun the setup command to recreate it:

pnpm run setup

Resolve Upload Failures After Deployment

If uploads fail but the rest of the application works, the bucket might not allow requests from your deployed web origin. See Allow Your Web Domain on the Bucket.

Port already in use

Stop whatever is running on port 3000 or 8000 and run pnpm dev again.

pnpm run doctor reports missing dependencies

Install the required version of Node.js or Python 3.12 or later, depending on which check failed. Then run pnpm run doctor again to confirm that the issue is resolved.

Next Steps

The repo includes detailed docs for each feature: