PocketPages

PocketPages is a 23KB pluggable Multi-Page Application (MPA) preprocessor designed specifically for PocketBase. It uses an EJS template engine by default and features a flexible plugin system that allows you to add features (such as different templating engines) while maintaining high performance.

Key characteristics:

• SEO-first: Optimized for search engine visibility.
• No build step: Simplifies development by removing the need for complex build pipelines.
• Fast SSR: Provides efficient server-side rendering.
• Pluggable: Choose only the features your application needs.

PocketPages is a web framework built on PocketBase that utilizes file-based routing and server-side rendering (SSR). It is designed for high performance using Golang and Goja, providing a lightweight footprint with minimal dependencies.

Key architectural pillars include:

• PocketBase Integration: Provides full access to the PocketBase JSVM API, native database integration, built-in authentication, and real-time capabilities.
• Server-Side Rendering: Delivers SEO-friendly pages with fast initial loads and reduced client-side JavaScript, including support for meta tags and OpenGraph.
• Routing: Uses an intuitive file-based routing system.
• Templating: Uses EJS for dynamic content generation.

PocketPages uses a plugin architecture to extend functionality beyond simple templating. Plugins can hook into different stages of the application lifecycle to perform the following tasks:

• Extend Request and Response: Use onRequest and onResponse hooks to modify how requests are processed and how responses are delivered.
• Customize Rendering: Use the onRender hook to intercept and modify the final output.
• Extend the API: Use the onExtendContextApi hook to add custom functions or integrate sub-applications into the API context.

The order of plugins in the plugins array determines the sequence of the onRender hook execution. The output of one plugin becomes the input for the next plugin in the array.

Example: Using EJS inside Markdown To use EJS features within Markdown files, you must place the EJS plugin before the Markdown plugin in the array. This ensures EJS processes the file first, and the resulting content is then passed to the Markdown plugin for HTML conversion.

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',
  ],
}

When using include(), the plugin performs a smart search for partials. It searches up the directory tree for _private directories. For a given path, it will:

1. Look for an exact match of the specified path.
2. If not found, try appending each configured extension.
3. Repeat this process by moving up the directory tree into _private folders.

Example: include('header') with extensions ['.ejs', '.md'] will search for header, header.ejs, and header.md within the current directory's _private folder, then the parent's _private folder, and so on, up to the root.

<%%%- include('header', { title: 'My Page' }) %>

<!-- You can also use explicit extensions -->
<%%%- include('header.ejs', { title: 'My Page' }) %>

When using requestOAuth2Login, keep the following security and configuration requirements in mind:

• CSRF Protection: The function automatically generates and stores a state parameter in a cookie to prevent Cross-Site Request Forgery attacks.
• Callback Validation: The state and other OAuth2 parameters are stored in a cookie to be validated during the callback phase.
• Redirect URL Matching: The final redirect URL is constructed using your application's base URL combined with the redirectPath option. Crucially, you must ensure this resulting URL matches exactly what you have configured in your OAuth2 provider's (e.g., Google, GitHub) developer settings.

Choose between echo() and logging functions based on where you want to see the output:

When using the pb() client in the JSVM environment, be aware of the following constraints:

• Synchronous Only: All SDK methods are synchronous; async/await is not supported/needed.
• No Realtime Subscriptions: You cannot use .subscribe() within hooks/JSVM.
• No AsyncAuthStore: The AsyncAuthStore is not supported.
• Caching: The client is cached after its first initialization.

Realtime capabilities in PocketPages rely on WebSocket connections, but the capabilities differ based on the environment:

• Server-Side (JSVM/Hooks): The JSVM environment does not support WebSocket connections, so you cannot subscribe to realtime events. You can only send realtime events to connected clients.
• Client-Side (Browser/Node.js): Using the PocketBase JavaScript SDK, you can both send and receive realtime events.

Always use the appropriate SDK for your environment: pocketbase-js-sdk-jsvm for server-side hooks and the standard pocketbase/js-sdk for client-side code.