Frontend Deployment

Frontend Architecture

pb-ext serves static files from the pb_public/ directory, making it compatible with any static site generator. The recommended approach is SvelteKit with the static adapter.

SvelteKit Integration

Project Setup

Create a SvelteKit application in the frontend/ directory:

npx sv create frontend

Configuration options:

Template: Skeleton project (or your preferred template)
Language: TypeScript (recommended)
Adapter: static-adapter (required for pb-ext compatibility)
Add-ons: ESLint, Prettier, Playwright (as needed)

Static Adapter Configuration

SvelteKit requires configuration for static site generation. Create frontend/src/routes/+layout.ts:

export const prerender = true;
export const trailingSlash = 'always';

boolean

default:true

Enable static prerendering for all routes

string

default:"always"

Ensure trailing slashes for consistent routing

Build Configuration

Ensure frontend/svelte.config.js uses the static adapter:

import adapter from '@sveltejs/adapter-static';

export default {
  kit: {
    adapter: adapter({
      pages: 'build',
      assets: 'build',
      fallback: 'index.html',
      precompress: false,
      strict: true
    })
  }
};

svelte-gui Starter Template

For a complete, production-ready SvelteKit setup, use the svelte-gui template:

git clone https://github.com/magooney-loon/svelte-gui.git

Features

Authentication UI

Pre-built login, signup, and profile pages

Dashboard Layout

Responsive admin dashboard with sidebar navigation

API Integration

PocketBase SDK integration and API examples

Dark Mode

Built-in theme switching with Tailwind CSS

Components

Reusable UI components and form elements

TypeScript

Full type safety with TypeScript

pb_public/ Directory Structure

The pb_public/ directory is where static files are served from:

pb_public/
├── index.html          # Main entry point
├── _app/
│   ├── immutable/     # Versioned assets (long cache)
│   └── version.json   # Build version
├── favicon.png
└── assets/            # Images, fonts, etc.

Path Resolution

pb-ext searches for pb_public/ in multiple locations:

./pb_public (current directory)
Executable directory + /pb_public
Executable directory + /../pb_public
Executable directory + /../../pb_public

The server logs the resolved pb_public path on startup for debugging.

Build Pipeline

Development Builds

The pb-cli toolchain handles frontend builds automatically:

# Build frontend + start dev server
pb-cli

# Build frontend only (no server)
pb-cli --build-only

# Skip frontend build (server only)
pb-cli --run-only

What pb-cli Does

Install dependencies

Runs npm install in the frontend/ directory (if needed)

Build frontend

Executes npm run build to generate static files

Copy to pb_public

Copies built assets from frontend/build/ to pb_public/

Generate OpenAPI specs

Creates API documentation (in dev mode, done at runtime)

Start server

Launches the pb-ext server at http://127.0.0.1:8090

Production Builds

Production builds optimize assets for deployment:

pb-cli --production

This creates an optimized build in dist/ with:

Minified JavaScript and CSS
Prerendered HTML pages
Compressed assets
Production-ready binary

Static File Serving

All files in pb_public/ are served at the root path:

File Path	URL
`pb_public/index.html`	`http://localhost:8090/`
`pb_public/about.html`	`http://localhost:8090/about`
`pb_public/assets/logo.png`	`http://localhost:8090/assets/logo.png`

Reserved routes (/_, /_/_, /api) take precedence over static files. Avoid naming conflicts.

Development vs Production

Development Mode

pb-cli

Hot module replacement (HMR) via SvelteKit dev server
Source maps enabled
Verbose logging
OpenAPI specs generated at runtime via AST parsing

Production Mode

pb-cli --production

Minified and optimized assets
No source maps
Structured logging only
OpenAPI specs read from disk (dist/specs/)
Binary optimization with -ldflags="-s -w"

Asset Optimization

Image Optimization

Use SvelteKit’s enhanced:img for automatic optimization:

<script>
  import { enhance } from '$app/forms';
  import heroImage from '$lib/assets/hero.jpg?enhanced';
</script>

<img src={heroImage} alt="Hero" />

Code Splitting

SvelteKit automatically code-splits routes:

// Lazy-load components
const HeavyComponent = () => import('./HeavyComponent.svelte');

Preloading

Preload critical routes for faster navigation:

<a href="/dashboard" data-sveltekit-preload-data="hover">
  Dashboard
</a>

API Integration

Connect your frontend to pb-ext APIs:

PocketBase SDK

Install the PocketBase JavaScript SDK:

cd frontend
npm install pocketbase

Client Setup

Create a PocketBase client in frontend/src/lib/pocketbase.ts:

import PocketBase from 'pocketbase';

export const pb = new PocketBase('http://127.0.0.1:8090');

// Auto-refresh auth
pb.autoCancellation(false);

Authentication Example

import { pb } from '$lib/pocketbase';

// Login
await pb.collection('users').authWithPassword(
  '[email protected]',
  'password'
);

// Get current user
const user = pb.authStore.model;

// Logout
pb.authStore.clear();

Frontend Detection

The build toolchain automatically detects frontend type:

# No frontend/ directory
# pb-cli creates empty pb_public/

# frontend/ exists but no package.json
# Files copied directly to pb_public/

# frontend/package.json exists
# npm install + npm run build + copy to pb_public/

Troubleshooting

404 errors for static files

Cause: Files not in pb_public/ or incorrect path.Solution:

Verify files exist in pb_public/
Check server logs for resolved pb_public path
Ensure paths are relative (no leading /)

Frontend build fails

Cause: Missing dependencies or build errors.Solution:

cd frontend
npm install
npm run build  # Test build directly

Assets not updating

Cause: Browser cache or build cache.Solution:

Hard refresh browser (Ctrl+Shift+R)
Delete pb_public/ and rebuild
Clear SvelteKit cache: rm -rf frontend/.svelte-kit

Prerender errors in SvelteKit

Cause: Dynamic routes without prerender configuration.Solution: Add +page.ts with prerender config:

export const prerender = true;

​Frontend Architecture

​SvelteKit Integration

​Project Setup

​Static Adapter Configuration

​Build Configuration

​svelte-gui Starter Template

​Features

Authentication UI

Dashboard Layout

API Integration

Dark Mode

Components

TypeScript

​pb_public/ Directory Structure

​Path Resolution

​Build Pipeline

​Development Builds

​What pb-cli Does

​Production Builds

​Static File Serving

​Development vs Production

​Development Mode

​Production Mode

​Asset Optimization

​Image Optimization

​Code Splitting

​Preloading

​API Integration

​PocketBase SDK

​Client Setup

​Authentication Example

​Frontend Detection

​Troubleshooting

​Next Steps

Production Deployment

Environment Configuration

Frontend Architecture

SvelteKit Integration

Project Setup

Static Adapter Configuration

Build Configuration

svelte-gui Starter Template

Features

pb_public/ Directory Structure

Path Resolution

Build Pipeline

Development Builds

What pb-cli Does

Production Builds

Static File Serving

Development vs Production

Development Mode

Production Mode

Asset Optimization

Image Optimization

Code Splitting

Preloading

API Integration

PocketBase SDK

Client Setup

Authentication Example

Frontend Detection

Troubleshooting

Next Steps