Pocketbase-turnkey-auth NPM

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

A running PocketBase instance with a users collection
An Express application
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.