pocketbase-turnkey-auth

A complete, ready-to-use authentication system for Express apps using PocketBase as the backend. This package provides beautifully styled login, registration, profile, and logout pages with minimal configuration.

Installation

pnpm add pocketbase-turnkey-auth

Or if you prefer npm:

npm install pocketbase-turnkey-auth

Prerequisites

1. A running PocketBase instance with a users collection
2. An Express application
3. Body parsing middleware configured (for handling form submissions)

PocketBase Setup

This package requires PocketBase as the backend database and authentication server.

PocketBase Documentation: https://pocketbase.io/docs/

PocketBase Download Links:

• Linux: pocketbase_0.25.8_linux_amd64.zip
• Windows: pocketbase_0.25.8_windows_amd64.zip
• macOS: pocketbase_0.25.8_darwin_amd64.zip

Quick Start

const express = require("express");
const { initTurnkeyAuth } = require("pocketbase-turnkey-auth");
const app = express();

// Parse form data and JSON
app.use(express.urlencoded({ extended: true }));
app.use(express.json());

// Initialize authentication with one line
initTurnkeyAuth(app, {
  pocketBaseUrl: "http://127.0.0.1:8090", // Your PocketBase URL
  routePrefix: "/auth"                    // Optional prefix for all auth routes
});

// Your other routes
app.get("/", (req, res) => {
  res.send(`
    <h1>Welcome to my app</h1>
    <p>
      <a href="/auth/login">Login</a> |
      <a href="/auth/register">Register</a>
    </p>
  `);
});

app.listen(3000, () => console.log("Server running on http://localhost:3000"));

Features

• Complete Authentication Flow: Registration, login, profile viewing, and logout
• Beautiful Styling: Clean, responsive design that works on all devices
• Error Handling: Proper validation and error messages
• Session Management: Uses express-session and Passport.js
• Security: Password hashing and secure session handling
• User-Friendly: Intuitive UI with helpful navigation between pages

Available Routes

After initializing with initTurnkeyAuth(app), the following routes are available:

| Route | Method | Description | |-------|--------|-------------| | /auth/ | GET | Redirects to profile if logged in, or login page if not | | /auth/register | GET | Shows registration form | | /auth/register | POST | Creates a new user account | | /auth/login | GET | Shows login form | | /auth/login | POST | Authenticates a user | | /auth/profile | GET | Shows user profile (protected route) | | /auth/logout | POST | Logs out the current user |

Configuration Options

initTurnkeyAuth(app, {
  // Required: URL to your PocketBase instance
  pocketBaseUrl: "http://127.0.0.1:8090",

  // Optional: Prefix for all auth routes (default: "/auth")
  routePrefix: "/auth",

  // Optional: Secret for session encryption (default: auto-generated)
  sessionSecret: "your-secret-key",

  // Optional: Additional express-session configuration
  sessionConfig: {
    cookie: {
      maxAge: 86400000, // 1 day
      secure: true      // Use with HTTPS
    }
  }
});

Accessing the Authenticated User

In your Express routes, you can access the authenticated user via req.user:

app.get("/dashboard", (req, res) => {
  if (!req.isAuthenticated()) {
    return res.redirect("/auth/login");
  }

  res.send(`
    <h1>Dashboard</h1>
    <p>Welcome, ${req.user.email}!</p>
    <a href="/auth/profile">View Profile</a>
  `);
});

Protecting Routes

You can create a middleware function to protect routes:

function isLoggedIn(req, res, next) {
  if (req.isAuthenticated()) return next();
  res.redirect("/auth/login");
}

// Use the middleware to protect routes
app.get("/dashboard", isLoggedIn, (req, res) => {
  res.send("Protected dashboard page");
});

Customization

The authentication pages come with a clean, modern design that works well with most websites. The styling is included inline with each page, making it easy to integrate into any application.

Example Screenshots

Here are screenshots of the authentication pages:

Login Page

Registration Page

Debugging

The package includes detailed console logging to help with debugging:

• Authentication attempts
• Registration events
• Login/logout events
• Session management

License

ISC License

Author

Lee Charles Laing [email protected]