spinspire/pocketbase-sveltekit-starter

You can extend the backend functionality in two ways:

• JavaScript Hooks: Easy development using JS. Example logic can be found in ./pb/pb_hooks/main.pb.ts. The server automatically hot-reloads when files in ./pb/pb_hooks change.
• Golang Extensions: Full performance. You can implement custom API endpoints (e.g., /api/hello) and database event hooks (e.g., executing Go handlers when a row is created) by modifying main.go. If using modd, the server will hot-reload when Go code changes.

This project uses a JAMstack architecture where the frontend is a fully static SvelteKit application and the backend is a single compiled PocketBase (Golang) binary.

Workflow:

1. The SvelteKit app is compiled into static files using adapter-static (SSR is disabled).
2. PocketBase serves the compiled SvelteKit app.
3. The Browser (client) makes API calls directly to the PocketBase server.

This combination provides high performance because the frontend requires no Node.js/Bun runtime at production, and the backend is a single, fast Go binary providing a database (SQLite), CRUD API, real-time subscriptions, Auth, and file storage.

Schema Migrations

PocketBase 0.9+ uses JavaScript auto-migrations. Changes made to the schema are automatically saved as JS files in the pb_migrations folder. Ensure you commit these files to version control.

Regenerating TypeScript Types

To keep your frontend in sync with your database collections, you must regenerate the generated-types.ts file whenever the schema changes. Run the typegen script located in the frontend's package.json.

You can start the backend using one of these methods:

• Directly: Run ./pocketbase serve in the pb directory.
• Via NPM: Run npm run backend from the sk directory.

If you want the PocketBase backend to also serve your frontend assets, you must include the --publicDir flag pointing to your build folder:

./pocketbase serve --publicDir ../frontend/build

Running PocketBase inside Docker is highly recommended. The repository includes:

• A Dockerfile for production images.
• A docker-compose.yml for development.
• A docker-compose.override.yml for development-specific configurations.

Using Docker also automates the setup of modd for Go live-reloading.

Use this method if you have Go tools installed and want to run the application directly on your OS without Docker.

1. Ensure Go is installed (go version).
2. In the /pb directory, run go mod tidy.
3. Build the binary: go build.
4. (Optional) For live development with hot-reloading of Go code, install modd:

   go install github.com/cortesi/modd/cmd/modd@latest

   Then run modd to start the backend development server.
5. In a new terminal, run the frontend: cd sk && npm run develop.

This method is suitable for simple use cases using only JavaScript-based customizations.

1. Download the latest PocketBase binary for your OS from the official releases.
2. Extract pocketbase.exe (or the relevant binary) into the /pb folder.
3. Backend: In the /sk directory, run npm run backend.
   • Windows Note: You must edit ./sk/package.json and change the backend script to: cd .. && cd pb && pocketbase serve --publicDir=../sk/build.
4. Frontend: In the /sk directory, install dependencies with npx pnpm install and run npm run dev.

Before starting the backend, you must apply the database schema migrations. Run the following command in the pb directory to create the necessary tables and collections:

./pocketbase migrate up

You can set up the backend in two ways:

1. Standard Release: Download the official binary from the PocketBase releases page, unzip it, and place the pocketbase binary in the pb directory. This version supports JavaScript extensions.
2. Custom Build: If you want to use PocketBase as a framework with Go-language customizations, use the provided main.go. You can build it using go build or use modd for live reloading.

Note: The entrypoint.sh script defaults to a custom build if a go compiler is detected; otherwise, it downloads the standard binary.

If you prefer not to use Docker, you can run the backend and frontend separately.

1. Backend Setup (in /pb folder):

• Initialize dependencies: go mod tidy
• Run the server: go run main.go serve --dev (runs at http://localhost:8090)
• Create admin user: Visit http://localhost:8090/_

2. Frontend Setup (in /sk folder):

• Install dependencies: bun install
• Run dev server: bun run dev (runs at http://localhost:5173)

Using Docker is the strongly recommended method, especially if you are customizing the backend with Go code.

1. Copy .env.example to .env and configure your environment variables.
2. (Optional) Copy docker-compose.override.yml.example to docker-compose.override.yml and edit as needed.
3. Run the following command:

   docker compose up -d

4. Access the frontend dev server at http://localhost:5173.
5. Access the backend admin setup at http://localhost:5173/_ to create your first admin user.
6. Verify the setup by visiting http://localhost:5173/hello to see if the 'Hello World!' API response appears.