Local Development

This guide will help you get PocketKit running on your local machine.

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js (v18 or higher)
• Package manager (npm, yarn, or pnpm)
• Git

Quick Setup (Recommended)

The fastest way to get started is using the automated setup script:

# Clone the repository
git clone https://github.com/stijnbakk/PocketKit.git
cd PocketKit

# Run the get started script
./GET-STARTED.sh

The script will prompt you to choose between:

1. SvelteKit (app-svelte directory)
2. React/Next.js (app-react directory)

Then it will automatically:

1. Initialize a fresh git repository
2. Install dependencies (auto-detects pnpm/yarn/npm)
3. Download PocketBase for your operating system
4. Create an initial commit

Once complete, start developing:

yarn

# For SvelteKit
cd app-svelte
yarn dev

# For React/Next.js
cd app-react
yarn dev

pnpm

# For SvelteKit
cd app-svelte
pnpm dev

# For React/Next.js
cd app-react
pnpm dev

npm

# For SvelteKit
cd app-svelte
npm run dev

# For React/Next.js
cd app-react
npm run dev

Tip

The GET-STARTED.sh script handles everything! Skip to Access the Application if you used this method.

Manual Setup

If you prefer to set up manually or the script doesn’t work for your system, follow these steps.

Project Structure

PocketKit provides two frontend options:

PocketKit/
├── app-svelte/    # SvelteKit frontend application
├── app-react/     # Next.js frontend application
├── server/        # PocketBase backend (shared by both)
└── docs/          # Documentation (Starlight)

Choose one app directory based on your preferred framework.

Install Dependencies

Navigate to your chosen app directory and install the dependencies:

yarn

# For SvelteKit
cd app-svelte
yarn install

# OR for React/Next.js
cd app-react
yarn install

pnpm

# For SvelteKit
cd app-svelte
pnpm install

# OR for React/Next.js
cd app-react
pnpm install

npm

# For SvelteKit
cd app-svelte
npm install

# OR for React/Next.js
cd app-react
npm install

Download PocketBase

For local development, you need to download the PocketBase executable:

1. Visit pocketbase.io
2. Download the appropriate version for your operating system
3. Place the pocketbase executable in the server/ directory

Note: Make sure the file is named pocketbase and is executable.

On macOS/Linux, you may need to make it executable:

chmod +x ../server/pocketbase

Start Development Server

From your chosen app directory, run:

SvelteKit:

yarn

cd app-svelte
yarn dev

pnpm

cd app-svelte
pnpm dev

npm

cd app-svelte
npm run dev

This single command will:

• Start the SvelteKit dev server on http://localhost:5173
• Launch PocketBase on http://localhost:8090

React/Next.js:

yarn

cd app-react
yarn dev

pnpm

cd app-react
pnpm dev

npm

cd app-react
npm run dev

This single command will:

• Start the Next.js dev server on http://localhost:3000
• Launch PocketBase on http://localhost:8090

Tip

The dev command in both apps runs both servers simultaneously. Check the respective package.json to see how this works:

SvelteKit (app-svelte/package.json):

{
  "scripts": {
    "dev": "yarn dev:app & yarn dev:server",
    "dev:app": "vite dev",
    "dev:server": "cd ../server && ./pocketbase serve"
  }
}

Next.js (app-react/package.json):

{
  "scripts": {
    "dev": "concurrently \"npm run dev:app\" \"npm run dev:server\"",
    "dev:app": "next dev",
    "dev:server": "cd ../server && ./pocketbase serve"
  }
}

Access the Application

Once both servers are running:

SvelteKit:

• Frontend: http://localhost:5173
• PocketBase Admin: http://localhost:8090/_

React/Next.js:

• Frontend: http://localhost:3000
• PocketBase Admin: http://localhost:8090/_

Set Up PocketBase Admin

On first run, you’ll need to create an admin account:

1. Visit http://localhost:8090/_
2. Create your admin email and password
3. This account is for managing your backend (users, collections, settings)

Environment Variables

Both apps use environment variables for configuration.

SvelteKit - Create .env in the app-svelte/ directory:

PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090

React/Next.js - Create .env.local in the app-react/ directory:

NEXT_PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090

Note

These are the default values for local development. When you deploy to production, you’ll update these to your Fly.io URL.

Development Workflow

Making Changes

Frontend code: Edit files in your chosen app directory - changes will hot reload automatically

• SvelteKit: app-svelte/src/
• Next.js: app-react/src/

Backend:

• Schema: Use the PocketBase admin UI at http://localhost:8090/_
• Hooks: Add JavaScript/TypeScript files to server/pb_hooks/ (requires PocketBase restart)

Database

PocketBase uses SQLite and stores all data in server/pb_data/. This directory is created automatically when you first run PocketBase.

Caution

The server/pb_data/ directory is gitignored. Your local database is separate from production.

Testing Authentication

Both apps include complete auth flows:

SvelteKit:

• Register: http://localhost:5173/auth/register
• Login: http://localhost:5173/auth/login
• Logout: Handled via the logout endpoint

React/Next.js:

• Register: http://localhost:3000/auth/register
• Login: http://localhost:3000/auth/login
• Logout: Click the logout button (handled via API route)

Create a test user to verify everything works.

Common Issues

Port Already in Use

If port 5173 or 8090 is already in use:

• SvelteKit: Stop the process using port 5173, or modify the port in vite.config.ts
• PocketBase: Stop any running PocketBase instances, or modify the port in the dev script

PocketBase Not Found

If you get an error about PocketBase not being found:

1. Make sure you downloaded the PocketBase executable
2. Verify it’s in the server/ directory
3. Ensure it’s named pocketbase (no file extension on macOS/Linux)
4. Verify it’s executable (chmod +x server/pocketbase on macOS/Linux)

Permission Denied (macOS)

On macOS, you might see a security warning when running PocketBase:

1. Go to System Settings → Privacy & Security
2. Look for a message about PocketBase being blocked
3. Click Allow Anyway
4. Run the dev command again

Next Steps

Now that you have PocketKit running locally:

• Explore the Authentication system to understand how auth works
• Learn how to Deploy to production
• Start building your app:
  • SvelteKit: Modify files in app-svelte/src/routes/
  • Next.js: Modify files in app-react/src/app/