How to Integrate Lucia with Modern Frameworks (Step by Step)
We’re building a user authentication system that integrates Lucia with frameworks like React and Next.js. Why? Because Lucia integration offers a streamlined and modern approach to authentication that many developers find appealing.
Prerequisites
- Node.js 14+, npm 7+
- React 17+, Next.js 12+
- Lucia 1.0+
- PostgreSQL or MongoDB for your database setup
Step 1: Setting Up Your Project
npx create-next-app my-auth-app
cd my-auth-app
npm install lucia
When you set up a new Next.js project, you’re getting the latest features and optimizations for SSR (Server-Side Rendering). You’ll also need to install Lucia for handling authentication efficiently. The above command initializes a React application, and you then install Lucia.
Step 2: Configuring Lucia
import { Lucia } from "lucia-auth";
const lucia = new Lucia({
adapter: 'mongodb', // select your adapter
env: 'development', // set your environment
database: 'my-db' // database name
});
This setup tells Lucia where to store user data. If you’ve chosen MongoDB, it’s straightforward. If you encounter errors related to your database connection, double-check that your MongoDB instance is running and the connection string is correct.
Step 3: Creating User Registration
app.post('/api/register', async (req, res) => {
const { username, password } = req.body;
try {
const user = await lucia.register(username, password);
res.status(200).json({ user });
} catch (error) {
res.status(400).json({ error: error.message });
}
});
The registration endpoint captures user data, validates it, and registers the user. It’s critical to handle errors appropriately, especially for issues like duplicate usernames or weak passwords. Failing to manage these can lead to confusing user experiences.
Step 4: Implementing User Login
app.post('/api/login', async (req, res) => {
const { username, password } = req.body;
try {
const session = await lucia.login(username, password);
res.status(200).json({ session });
} catch (error) {
res.status(400).json({ error: error.message });
}
});
User login is similar to registration but in reverse. You authenticate and create a session. If you mess this up, you might allow unauthorized access or deny legitimate users. Always include some logging to catch these types of issues early.
Step 5: Protecting Routes
const withAuth = (handler) => async (req, res) => {
const session = getSession(req);
if (!session) {
return res.status(401).json({ error: 'Unauthorized' });
}
return handler(req, res);
};
app.get('/api/protected', withAuth(async (req, res) => {
res.status(200).json({ message: 'This is protected data' });
}));
Protecting specific routes ensures that only authenticated users can access certain API endpoints. Misconfigurations often lead to either complete accessibility or unexpected restrictions. Testing this rigorously is a must.
The Gotchas
- Database Connection Issues: If your database isn’t set up right, you’ll spend hours staring at connection errors. Always mock your DB to isolate issues.
- Session Management: Session expiry or deletion can lock users out unexpectedly. Make sure to clearly define session lifetimes based on user needs.
- Password Storage: Remember to hash passwords securely. Lucia will help, but if you’ve turned off security features, you’re in trouble.
- Environment Variables: Keep your secrets safe. Make sure they’re loaded properly in different environments. It’s easy to forget to configure these in production.
- Handling CORS: If you’re serving your API from a different domain, configuration errors can lead to being blocked. Fine-tune CORS settings to ensure smooth operation.
Full Code Example
import express from 'express';
import { Lucia } from 'lucia-auth';
const app = express();
app.use(express.json());
const lucia = new Lucia({
adapter: 'mongodb',
env: 'development',
database: 'my-db'
});
app.post('/api/register', async (req, res) => {
const { username, password } = req.body;
try {
const user = await lucia.register(username, password);
res.status(200).json({ user });
} catch (error) {
res.status(400).json({ error: error.message });
}
});
app.post('/api/login', async (req, res) => {
const { username, password } = req.body;
try {
const session = await lucia.login(username, password);
res.status(200).json({ session });
} catch (error) {
res.status(400).json({ error: error.message });
}
});
const withAuth = (handler) => async (req, res) => {
const session = getSession(req); // Assume this function is defined somewhere
if (!session) {
return res.status(401).json({ error: 'Unauthorized' });
}
return handler(req, res);
};
app.get('/api/protected', withAuth(async (req, res) => {
res.status(200).json({ message: 'This is protected data' });
}));
app.listen(3000, () => {
console.log('Server running on port 3000');
});
What’s Next
Set up email verification for new users. It’s not just about making their login secure; it’s also about validating their email addresses to reduce spam accounts.
FAQ
- What if I want to use a different database?
- Lucia supports multiple adapters. Check the documentation for specifics on integrating with those databases.
- Can I use Lucia with existing user databases?
- Yes, but you may need to adjust your user schema to match Lucia’s requirements.
- How do I handle custom authentication logic?
- You can hook into Lucia’s authentication methods and build custom flows based on your app’s needs.
Data Sources
For official guidance, check out the following resources:
| Resource | Link |
|---|---|
| Lucia Documentation | lucia.auth.dev/docs |
| Next.js Documentation | nextjs.org/docs |
| MongoDB Documentation | docs.mongodb.com |
Last updated April 26, 2026. Data sourced from official docs and community benchmarks.
🕒 Published: