pocketbase-turnkey-auth v1.0.4
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.
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 lcharleslaing@gmail.com