<%= data.product.name %>
<%= data.product.description %>
Product: <%= params.productId %>
Product: <%= params.productId %>
Review: <%= params.reviewId %>
` ## Query Parameters Query parameters come from the URL's query string (after the `?`). They're also available through `params`: `/products/123?sort=latest&highlight=true ` Access them the same way in templates: `Sort by: <%= params.sort %>
Highlight: <%= params.highlight %>
` ## Parameter Priority Query parameters override route parameters when they have the same name: `/products/123?productId=789 ` Here, `params.productId` will be `789`, not `123`. ## Complete Example URL: `/products/123/reviews/456?sort=latest&highlight=true ` Template: ```Product: <%= params.productId %>
Review: <%= params.reviewId %>
Sort by: <%= params.sort %>
Highlight: <%= params.highlight %>
``` ## Documentation: /loading-data # Loading Data in PocketPages There are several ways to load data in PocketPages, from simple inline loading to more structured approaches. ## Inline Data Loading The simplest way to load data is directly in your template using `<% %>` tags at the top of your file: `<% const products = findRecordsByFilter('products', { filter: 'active = true', sort: 'name' }) %>Products
<% products.forEach(product => { %><%= product.name %>
Products by Category
<% categories.forEach(category => { %><%= category.name %>
<% const categoryProducts = products.filter(p => p.category === category.id) %> <% categoryProducts.forEach(product => { %> <% }) %>
<% }) %> ` ## Structured Data Loading with +load.js For more complex data loading needs, PocketPages provides `+load.js` files. These are useful when you need to: - Share data loading logic across multiple templates - Separate concerns between data loading and presentation - Handle complex routing scenarios - Implement method-specific loading (GET, POST, etc.) ### Basic Usage `/** @type {import('pocketpages').PageDataLoaderFunc} */ module.exports = function (api) { const { findRecordsByFilter } = api const products = findRecordsByFilter('products', { filter: 'active = true', sort: 'name', }) return { products } } ` ## File Structure Data loaders follow your route hierarchy: `pb_hooks/pages/ +load.js # Only executes if index.ejs is the entry point index.ejs # Home page entry point products/ +load.js # Only executes if products/index.ejs is the entry point [id]/ +load.js # Only executes if products/[id]/index.ejs is the entry point +get.js # Only executes for GET requests if products/[id]/index.ejs is the entry point index.ejs # Template using data ` Important: Only a single `+load.js` file executes per request - the one at the same level as the entry point EJS file. This is different from `+middleware.js` files, which execute hierarchically from root to leaf along the route path. Use middleware when you need cascading data loading. ### Example: Route `/products/123` If the route resolves to `/products/123/index.ejs`: - Loader Execution (single file): `/products/[id]/+load.js # Only this loader executes ` - Method-Specific Loader Execution (single file): `/products/[id]/+get.js # Only this method-specific loader executes ` - Template Rendering: `/products/[id]/index.ejs ` ## Example Scenarios ### Product List (`/products`) ``` /** @type {import('pocketpages').PageDataLoaderFunc} */ module.exports = function (api) { const { findRecordsByFilter } = api const products = findRecordsByFilter('products', { filter: 'active = true', sort: '-created', }) return { products } } ``` ### Product Details (`/products/[id]`) ``` /** @type {import('pocketpages').PageDataLoaderFunc} */ module.exports = function (api) { const { findRecordByFilter, params, response } = api const product = findRecordByFilter('products', { filter: `id = "${params.id}"`, }) if (!product) { response.status(404) return { error: 'Product not found' } } return { product } } ``` ## HTTP Method-Specific Loaders In addition to `+load.js`, PocketPages supports method-specific loaders that only execute for their respective HTTP methods: `pb_hooks/pages/ contact/ +load.js # Runs for all methods +get.js # Runs only for GET, after +load.js +post.js # Runs only for POST, after +load.js index.ejs ` ### Execution Order - `+load.js` executes first (if present) - Method-specific loader executes second (if present) - Data from both loaders is merged ### Example: Contact Form ``` // contact/+load.js - Runs for all methods /** @type {import('pocketpages').PageDataLoaderFunc} */ module.exports = function (api) { return { departments: findRecordsByFilter('departments', { filter: 'active = true', }), } } // contact/+get.js - Runs only for GET requests /** @type {import('pocketpages').PageDataLoaderFunc} */ module.exports = function (api) { return { csrf: generateToken(), } } // contact/+post.js - Runs only for POST requests /** @type {import('pocketpages').PageDataLoaderFunc} */ module.exports = function (api) { const { formData, redirect } = api try { const message = findRecordByFilter('messages', { create: { email: formData.email, message: formData.message, department: formData.department, }, }) redirect('/contact/success') } catch (error) { return { error: 'Failed to send message', values: formData, } } } ``` ### Available Method Loaders - `+load.js` - Runs for all HTTP methods - `+get.js` - GET requests only - `+post.js` - POST requests only - `+put.js` - PUT requests only - `+patch.js` - PATCH requests only - `+delete.js` - DELETE requests only Note: Method-specific loaders are optional. If not present, only `+load.js` (if it exists) will execute. ## Using Data in Templates ### Basic Example ``` <%= product.name %>
<%= data.siteName %>
``` ### Complete Example ```Error: <%= data.error %>
<% } else if (data.product) { %>Products
<% data.products.forEach(product => { %>
<%= product.name %>
<% }) %><%= title %>
<% if (user) { %> <% } %>Welcome to My Application
Product Details
This is the main content of the product page.
` Then in your layout, access these named slots using the `slots` object: ` <%- slot %>
` Note the following patterns: - The `slot` variable always contains the complete content, whether or not slots are defined - Use `slots.name` to access a specific named section - Provide defaults with `slots.name || 'Default Content'` - Use `slots.body || slot` to create a main content area that shows either the body slot or all content ### Leaf `+load.js` Data Availability In layouts, the `data` object from the `+load.js` file at the leaf level (e.g., `index.ejs`) is available. However, it is important to note that the `data` object from the `+load.js` file at the layout level is not available in the layout itself. This means that the layout can access only the data passed from the leaf page. ### When Layouts are Not Applied Layouts are only applied to leaf EJS files that return HTML content. If an EJS file returns a JSON response, the layouts will not be executed. This ensures that layouts are used only for rendering HTML pages, keeping API responses clean and efficient. ## Documentation: /structure # Recommended Project Structure This recommended project structure makes it easy to upload everything in `/pb_*` directly to your production PocketBase instance. It also mirrors the directory structure of [pockethost.io](https://pockethost.io) and PocketBase's sample directory names. ``` package.json pb_hooks/ pages/ +boot.pb.js index.ejs pb_migrations/ pb_data/ storage/ data.db logs.db ``` ## Documentation: /private-files # Working with Private Files and Directories ## File Naming Conventions PocketPages has two special naming conventions: - Directories named `_private` are used for private files and are never publicly routable - Files that begin with `+` (like `+load.js` and `+layout.ejs`) are special PocketPages files and are not routable Examples: `pb_hooks/ pages/ _private/ # Private directory (not routable) helpers/ # Normal directory (routable) +load.js # Special PocketPages file (not routable) +layout.ejs # Special PocketPages file (not routable) index.ejs # Normal route file (routable) ` PocketPages implements a powerful system for managing private files through `_private` directories. This system serves two main purposes: - Organizing and including template partials via `include()` - Loading JavaScript modules via `resolve()` Both functions follow the same directory traversal pattern, making it intuitive to organize and access private files throughout your application. ## The `_private` Directory System ### Core Concepts - Directories named `_private` are never publicly routable - Files are resolved by searching `_private` directories up the directory tree - Each section can have its own private files - Child directories can override parent files of the same name - Files can be "hoisted" to ancestor directories to be shared ### Example Directory Structure `pb_hooks/ pages/ _private/ # Global shared files layout.ejs # Base layout template auth.js # Authentication utilities config.js # Global configuration products/ _private/ # Product-specific files product-card.ejs # Product display partial queries.js # Product database queries categories/ _private/ # Category-specific files category-nav.ejs # Category navigation partial helpers.js # Category-specific utilities index.ejs index.ejs index.ejs ` ## File Resolution When you call `include()` or `resolve()`, PocketPages: - Starts in the current template's directory - Looks for the file in that directory's `_private` folder - If not found, moves up to the parent directory and checks its `_private` folder - Continues until the file is found or reaches the root This creates a natural hierarchy where: - Files used by many pages live higher in the tree - Files specific to a section stay close to where they're used - Override files when needed by creating local versions ### Example Resolution `<% // In /products/categories/index.ejs: // Looks for category-nav first in local _private, then up the tree include('category-nav.ejs') // Uses /products/categories/_private/category-nav.ejs // Product card isn't in local _private, so checks parent directories include('product-card.ejs') // Uses /products/_private/product-card.ejs // Global layout is found in the root _private include('layout.ejs') // Uses /_private/layout.ejs // Same pattern works for resolve const helpers = resolve('helpers') // Uses local /categories/_private/helpers.js const queries = resolve('queries') // Uses parent /products/_private/queries.js const config = resolve('config') // Uses root /_private/config.js %> ` ## Path Control While the automatic resolution system handles most cases elegantly, you sometimes need more control: `// Absolute paths start from the root include('/products/_private/product-card.ejs') resolve('/products/_private/queries') // Use ../ to skip the local _private and force parent resolution include('../layout.ejs') resolve('../helpers') ` ## Best Practices ### 1. Proximity Principle Keep private files close to where they're used: `products/ _private/ product-card.ejs # Used only in products section product-queries.js # Product-specific database logic index.ejs ` ### 2. Strategic Hoisting Move files up the tree when they become widely used: `_private/ layout.ejs # Used across the site auth.js # Global authentication products/ _private/ product-card.ejs # Used only in products ` ### 3. Logical Overrides Override parent files when needed for specialization: `_private/ header.ejs # Default site header admin/ _private/ header.ejs # Special admin header ` ### 4. Clean Interfaces Export clear, focused interfaces from JavaScript modules: `// _private/database.js module.exports = { query: (sql, params) => { // Database query logic }, getRecord: (id) => { // Record retrieval logic }, } ` ## Important Notes - Files in `_private` directories are never publicly accessible - Changes to private files require a server restart in production - Use environment variables for secrets, not private files - Private files are perfect for: Reusable template components - Server-side utilities - Configuration - Database queries - Business logic ## The Power of Convention This system's strength comes from its conventions: - Predictable file location - Natural code organization - Clear separation of concerns - Easy code sharing - Simple overrides - Minimal path management By following these patterns, you can build maintainable applications where code lives where it makes sense, while still being easy to find and use. See [resolve](/docs/api/resolve) and [Using Partials](/docs/partials) for detailed documentation of the specific functions. ## Documentation: /middleware # Middleware Middleware files (`+middleware.js`) process requests before they reach your templates. Use middleware to: - Check authentication - Load shared data - Set headers - Validate requests - Handle errors ## Basic Example `/** @type {import('pocketpages').MiddlewareLoaderFunc} */ module.exports = function (api) { const { request, redirect } = api // Check auth if (!request.header('Authorization')) { redirect('/login') return {} } // Load data const categories = findRecordsByFilter('categories', { filter: 'active = true', }) return { categories } } ` ## How Middleware Works Middleware executes hierarchically from root to leaf: `pb_hooks/pages/ +middleware.js # Runs first (all routes) products/ +middleware.js # Runs second (/products/*) [id]/ +middleware.js # Runs third (/products/[id]/*) ` For URL `/products/123`: - `/+middleware.js` runs - `/products/+middleware.js` runs - `/products/[id]/+middleware.js` runs ## Common Use Cases ### Auth Guard `/** @type {import('pocketpages').MiddlewareLoaderFunc} */ module.exports = function (api) { const { request, redirect } = api const session = request.cookie('session') if (!session) { redirect('/login') return {} } const user = findRecordByFilter('users', { filter: `session = "${session}"`, }) return { user } } ` ### Request Validation ``` /** @type {import('pocketpages').MiddlewareLoaderFunc} */ module.exports = function (api) { const { request, response, params } = api if (!params.id?.match(/^[0-9]+$/)) { response.status(400) return { error: 'Invalid ID' } } return {} } ``` ### Loading Data ``` /** @type {import('pocketpages').MiddlewareLoaderFunc} */ module.exports = function (api) { const { params, response } = api const product = findRecordByFilter('products', { filter: `id = "${params.id}"`, }) if (!product) { response.status(404) return { error: 'Not found' } } return { product } } ``` ## Using Middleware Data Access middleware data in templates through `data`: `<% if (data.user) { %> Welcome, <%= data.user.name %>
<% if (data.product) { %><%= data.product.name %>
<%= data.product.description %>
<% } %> <% } %> ` ## Important Notes - Middleware runs before page loaders (`+load.js`) - All middleware along the route path executes - Return an object to pass data to templates - Return early to stop processing - Keep processing efficient ## HTTP Method-Specific Middleware In addition to `+middleware.js` which runs for all HTTP methods, you can create method-specific middleware files that only run for specific HTTP methods: `// +get.js - Only runs for GET requests /** @type {import('pocketpages').MiddlewareLoaderFunc} */ module.exports = function (api) { // Handle GET requests return {} } // +post.js - Only runs for POST requests /** @type {import('pocketpages').MiddlewareLoaderFunc} */ module.exports = function (api) { // Handle POST requests return {} } ` Supported method-specific middleware files: - `+get.js` - `+post.js` - `+put.js` - `+patch.js` - `+delete.js` These files follow the same hierarchical execution order as `+middleware.js`. ## Reference - [Loading Data Guide](/docs/loading-data) - [API Documentation](/docs/api) ## Documentation: /asset-management # Asset Management PocketPages provides built-in asset management with content-based fingerprinting for efficient cache invalidation. ## Directory Structure Place your static assets (images, CSS, JS, etc.) alongside the pages that use them: `pb_hooks/ pages/ feature/ index.md # Your content styles.css # Feature-specific styles header.jpg # Feature-specific image shared/ logo.png # Shared across pages ` ## Using Assets ### In Markdown Use standard markdown syntax for images - paths are automatically resolved relative to the current file: ` # Local image  # Absolute path ` ### In EJS Templates Use the `asset()` helper to generate fingerprinted URLs: ` %>)
` ## How It Works - During startup, PocketPages generates content-based fingerprints for all static files - The `asset()` helper and markdown images automatically generate fingerprinted URLs - URLs are served with long-term cache headers for optimal performance ## Best Practices - Keep assets close to the pages that use them - Use a shared directory (like `shared/` or `assets/`) for common resources - Always verify assets exist in your pages directory For detailed information about the `asset()` helper and its features, see the [asset helper documentation](/docs/request-context/asset). ## Documentation: /static-content # Serving Static Content in PocketPages In PocketPages, serving static content is straightforward and integrated seamlessly into the framework. Any file that isn't an EJS template (`*.ejs`), doesn't begin with a `+`, and isn't in a `_private` directory is treated as a static file. These files are served directly by the underlying Echo framework, which handles content type inference, streaming, and other necessary details. ## What is Considered Static Content? Static content refers to files that are served directly to the client without server-side processing or dynamic generation. These files typically include: - HTML files (`*.html`) - CSS files (`*.css`) - JavaScript files (`*.js`) - Image files (`*.jpg`, `*.png`, etc.) - Font files (`*.woff`, `*.ttf`, etc.) - Other binary files or documents (e.g., PDFs, videos) For dynamic asset handling in your templates and pages, PocketPages provides the `asset()` function that helps generate correct URLs for your static assets. This function ensures your assets are properly referenced regardless of your application's base path configuration. For more details on managing and organizing your static assets effectively, see the [Asset Management Guide](/docs/guides/asset-management). ### Example Directory Structure ``` my-pocketpages-app/ ├── pages/ │ ├── assets/ # Static assets directory │ │ ├── css/ │ │ │ ├── main.css │ │ │ └── components.css │ │ ├── js/ │ │ │ ├── app.js │ │ │ └── utils.js │ │ ├── images/ │ │ │ ├── logo.png │ │ │ └── hero.jpg │ │ └── fonts/ │ │ ├── OpenSans.woff2 │ │ └── Roboto.woff2 │ ├── documents/ # Static documents │ │ ├── terms.pdf │ │ └── privacy.pdf │ ├── layout.ejs # Layout template (not served as static) │ ├── +middleware.js # Middleware file (not served as static) │ ├── index.ejs # Dynamic page template │ └── about.html # Static HTML page ``` ## Documentation: /secrets # Managing Secrets in PocketPages When building secure applications, managing secrets like API keys, database credentials, and other sensitive information is crucial. PocketPages provides a secure way to access environment variables through the global `env()` function. ## Using the `env()` Function The `env()` function is available globally in both templates and JavaScript files. It provides secure access to environment variables: `const apiKey = env('API_KEY') const dbPassword = env('DB_PASSWORD') ` ### In Templates ``` <% const apiKey = env('API_KEY') %> ``` ### In JavaScript Files ``` /** @type {import('pocketpages').PageDataLoaderFunc} */ module.exports = function () { const apiKey = env('API_KEY') const dbUrl = env('DATABASE_URL') // Use environment variables for configuration return { config: { apiEndpoint: env('API_ENDPOINT'), // ... }, } } ``` ## Best Practices - Never Expose Secrets in Templates ` ` - Check for Required Variables `const apiKey = env('API_KEY') if (!apiKey) { error('Missing required API_KEY environment variable') // Handle error appropriately } ` - Use Descriptive Names `// Good const stripeSecretKey = env('STRIPE_SECRET_KEY') const mailgunApiKey = env('MAILGUN_API_KEY') // Avoid const key = env('KEY') const secret = env('SECRET') ` - Document Required Variables `/** * Required environment variables: * - API_KEY: External service API key * - DB_PASSWORD: Database password * - SMTP_PASSWORD: Email service password */ ` ## Setting Environment Variables Environment variables can be set in various ways depending on your deployment environment: - Development Environment `# .env file API_KEY=your_api_key DB_PASSWORD=your_db_password ` - Production Environment `# Set directly in your hosting environment export API_KEY=your_api_key export DB_PASSWORD=your_db_password ` - Docker Environment ``` ENV API_KEY=your_api_key ENV DB_PASSWORD=your_db_password ``` ## Security Considerations - Never commit secrets to version control - Use different values for development and production - Rotate secrets regularly - Use environment-specific configurations - Implement proper access controls ## Additional Resources - [Environment Variables Documentation](/docs/global-api/env) - [Deployment Guide](/docs/deploying) - [Security Best Practices](/docs/security) ## Documentation: /config # Custom Configuration with `+config.js` In the `pb_hooks/pages/` root, you can create a `+config.js` file to define custom configuration options for your application. This file allows you to control how files are processed within your app through plugins and other settings. `pb_hooks/ pages/ +config.js ` ## Example Configuration Here is an example of a basic `+config.js` file: `module.exports = { plugins: [ // String format (shorthand) 'pocketpages-plugin-ejs', // Object format with name { name: 'pocketpages-plugin-ejs', // npm package name extensions: ['.ejs', '.md'], debug: false, }, // Direct factory function (config, options) => ({ // plugin implementation }), // Object format with explicit factory function { fn: (config, options) => ({ // plugin implementation }), debug: false, // other options... }, ], debug: false, } ` ## Configuration Options - `plugins`: An array that specifies which plugins to use and their configurations. Plugins can be specified in several ways: As a string (shorthand for npm package name) - As an object with `name` property specifying an npm package - As a plugin factory function directly - As an object with `fn` property containing a factory function The `debug` option defaults to `false` for all plugin formats. - `debug`: A boolean that enables internal PocketPages debugging output to the console. When set to `true`, it will output information about routes, parameters, and other internal details that are helpful for troubleshooting. Defaults to `false`. ## Plugin Configuration Formats PocketPages supports several formats for configuring plugins. Here are all the valid formats: ## Plugin Processing Order The order of plugins in the `plugins` array determines their processing order. Each plugin's `onRender` hook is called in sequence, with the output of one plugin becoming the input for the next. For example, when processing a Markdown file with both EJS and Markdown plugins: `module.exports = { plugins: [ // Processes first - enables EJS in Markdown { name: 'pocketpages-plugin-ejs', extensions: ['.ejs', '.md'], }, // Processes second - converts Markdown to HTML 'pocketpages-plugin-marked', ], } ` This configuration allows you to: - Use EJS features within Markdown files - Process the resulting content as Markdown - Output the final HTML Changing the order would process Markdown first, then EJS - which might be desirable in some cases but would prevent using EJS features within Markdown files. `module.exports = { plugins: [ // Format 1: String shorthand (npm package name) 'pocketpages-plugin-ejs', // Format 2: Object with npm package name { name: 'pocketpages-plugin-ejs', debug: false, // Any other options are passed to the plugin extensions: ['.ejs', '.md'], }, // Format 3: Direct factory function (config, options) => ({ onRequest(context) { config.global.dbg('Request:', context.request.method) }, }), // Format 4: Object with explicit factory { fn: (config, options) => ({ onRequest(context) { config.global.dbg('Request:', context.request.method) }, }), debug: false, // Any other options are passed to the plugin }, ], } ` Important notes: - The `name` property should be the name of an npm package that exports a plugin factory - PocketPages plugins typically follow the naming convention `pocketpages-plugin-*` (e.g. `pocketpages-plugin-ejs`, `pocketpages-plugin-marked`) - If both `fn` and `name` are present in an object configuration, `fn` takes precedence - The `fn` property is the only reserved key in plugin configuration objects - All other properties in plugin configuration objects are passed as options to the plugin - The `debug` option defaults to `false` for all plugin formats ## Debug Options PocketPages provides two levels of debug output control: - Global debugging - Set via the top-level `debug` option. When true, enables debug output for all of PocketPages. - Per-plugin debugging - Each plugin can have its own `debug` option. This allows you to enable debug output for specific plugins while keeping others quiet. The plugin's debug option only affects debug calls within that plugin's scope. For example, to debug only the EJS plugin: ``` module.exports = { plugins: [ { name: 'pocketpages-plugin-ejs', debug: true, // Only EJS plugin will output debug info }, 'pocketpages-plugin-marked', // Debug defaults to false ], debug: false, // Global debugging remains off } ``` ## Documentation: /caching # Understanding Caching in PocketPages PocketPages uses content-based fingerprinting for static assets and development-mode cache busters to ensure efficient caching while maintaining quick updates during development. ## Asset Fingerprinting ### How It Works - During startup, PocketPages computes SHA-256 fingerprints for all static assets - The `asset()` helper embeds these fingerprints into filenames - The router dynamically matches fingerprinted URLs to their actual files `  %>)
` ### File Resolution PocketPages resolves asset paths relative to the current template: `pb_hooks/pages/ feature/ index.ejs # asset('image.png') → /feature/image.[hash].png image.png products/ details.ejs # asset('style.css') → /products/style.[hash].css style.css ` ## Development vs Production ### Development Mode When an asset doesn't exist in development: `  %>)
` ### Production Mode When an asset doesn't exist in production: ` 
` ## Best Practices - Keep Assets in Pages Directory `pb_hooks/pages/ images/ # Global images get fingerprinted logo.png feature/ header.jpg # Local images get fingerprinted index.ejs ` - Use Relative Paths for Local Assets `  %>){kind=logo}
` - Verify Assets Exist Missing assets won't get fingerprinted - Development mode will show cache busters - Production mode will serve un-fingerprinted paths ## CDN Integration ### Cloudflare Example Fingerprinted assets work well with CDNs: - First request: `/images/logo.abc123de.png` CDN misses, fetches from origin - Origin matches `abc123de` to `logo.png` - CDN caches response indefinitely - Content update: File changes, new hash `xyz789fg` - Template outputs `/images/logo.xyz789fg.png` - CDN misses, fetches new version - Old version naturally expires ### Cache Control Headers ``` /** @type {import('pocketpages').MiddlewareLoaderFunc} */ module.exports = function (api) { const { response } = api // Set cache headers for static assets response.header('Cache-Control', 'public, max-age=31536000') return {} } ``` ## Complete Example ``` ``` ## Important Notes - Fingerprinting requires files to exist in pages directory - Development mode helps identify missing assets - CDNs can cache fingerprinted assets indefinitely - Use middleware to set cache control headers - Relative paths for local assets, absolute for global ## Reference - [asset() Documentation](/docs/api/asset) - [Middleware Guide](/docs/middleware) - [Cloudflare Cache Documentation](https://developers.cloudflare.com/cache)