404 Lab

Transform your error pages from boring to extraordinary. A production-ready collection of beautifully crafted, interactive 404 error page components that turn user frustration into delight.

Overview

404 Lab is a modern, full-stack Next.js application that provides a comprehensive library of creative and interactive 404 error page components. Instead of showing users a generic "Page Not Found" message, transform that moment into an engaging experience with themed, animated, and interactive error pages inspired by popular brands and creative concepts.

Why 404 Lab?

User Experience First: Turn error pages into engaging experiences
Production Ready: Enterprise-grade code with TypeScript
Highly Customizable: Each component is fully customizable and documented
Copy & Paste: Easy integration with comprehensive documentation
Modern Stack: Built with the latest Next.js, React, and TypeScript

CLI Tool

404Lab CLI - Generate Custom 404 Pages Instantly

The 404Lab CLI is a powerful command-line tool that lets you add beautiful, pre-built 404 error pages to your Next.js projects with a single command. No manual file copying, no configuration hassle—just instant, production-ready error pages.

Overview

404Lab is an npm package that provides a seamless way to integrate professionally designed 404 error pages into your Next.js applications. Choose from 15+ stunning templates and add them to your project in seconds.

# Install globally
npm install -g 404lab

# Or use with npx (no installation required)
npx 404lab add simple

Key Features

Zero Configuration: Works out of the box with Next.js 13+ (App Router)
15+ Premium Templates: Choose from carefully crafted designs
Instant Setup: Add components with a single command
TypeScript Support: Full type safety included
Dependency Management: Automatically detects missing dependencies
Smart File Placement: Files are created in the correct Next.js directories
List & Preview: Browse available templates before installing
Easy Removal: Clean uninstall with the remove command

Installation

Global Installation (Recommended)

npm install -g 404lab

Use with npx (No Installation)

npx 404lab <command>

Requirements

Node.js: >= 16.0.0
Next.js: >= 13.0.0 (App Router)
Package Manager: npm, yarn, or pnpm

Commands

`404lab add <template>`

Add a 404 page template to your Next.js project.

404lab add modern

Options:

<template> - Template name (required)
--path <path> - Custom output path (optional)
--force - Overwrite existing files (optional)

Example:

# Add the Modern template
404lab add modern

# Add with custom path
404lab add terminal --path ./app/custom-404

# Force overwrite existing files
404lab add snow --force

What it does:

Validates your Next.js project structure
Copies the selected template to app/not-found.tsx
Installs required dependencies (if missing)
Creates necessary component files in components/404/
Confirms successful installation

`404lab list`

Display all available 404 page templates.

404lab list

Output:

Available 404 Page Templates:

  1. simple          - Clean, minimalist design
  2. modern          - Contemporary with animations
  3. google          - Google-inspired layout
  4. vercel          - Vercel-style error page
  5. terminal        - Interactive terminal UI
  6. macos           - macOS system UI style
  7. retrotv         - Vintage TV aesthetic
  8. blueglitch      - Cyberpunk glitch effects
  9. particles       - Animated particle system
  10. snow           - Falling snow animation
  11. poet           - Artistic, poetic design
  12. stoneage       - Prehistoric themed
  13. strangerthings - 80s sci-fi inspired
  14. amongus        - Game-inspired design
  15. geeksforgeeks  - Educational platform style

Usage: 404lab add <template-name>

Options:

--detailed - Show additional template information
--json - Output in JSON format

`404lab remove`

Remove the currently installed 404 page template.

404lab remove

Options:

--keep-deps - Keep installed dependencies
--yes - Skip confirmation prompt

Example:

# Remove with confirmation
404lab remove

# Remove without confirmation
404lab remove --yes

# Remove but keep dependencies
404lab remove --keep-deps

What it does:

Removes app/not-found.tsx
Cleans up component files from components/404/
Optionally removes unused dependencies
Restores default Next.js 404 behavior

Available Templates

Template Name	Style	Dependencies	Complexity
`simple`	Minimalist	None	⭐ Beginner
`modern`	Contemporary	None	⭐ Beginner
`google`	Brand-inspired	None	⭐ Beginner
`vercel`	Brand-inspired	None	⭐⭐ Intermediate
`geeksforgeeks`	Educational	None	⭐⭐ Intermediate
`terminal`	Developer	None	⭐⭐ Intermediate
`macos`	System UI	None	⭐⭐ Intermediate
`retrotv`	Vintage	None	⭐⭐ Intermediate
`blueglitch`	Glitch effect	None	⭐⭐⭐ Advanced
`particles`	Interactive	@tsparticles/*	⭐⭐⭐ Advanced
`snow`	Seasonal	@tsparticles/*	⭐⭐⭐ Advanced
`poet`	Artistic	None	⭐⭐ Intermediate
`stoneage`	Themed	None	⭐⭐ Intermediate
`strangerthings`	Pop culture	None	⭐⭐⭐ Advanced
`amongus`	Game-inspired	None	⭐⭐⭐ Advanced

How It Works

File Placement

When you run 404lab add <template>, the CLI automatically creates files in the correct Next.js App Router structure:

your-nextjs-project/
├── app/
│   └── not-found.tsx          # 👈 Main 404 page (created here)
├── components/
│   └── 404/
│       └── [TemplateName].tsx # 👈 Component files (created here)
└── package.json

Template Selection

Browse templates: Run 404lab list to see all available options
Choose one: Pick a template based on your project's style
Install it: Run 404lab add <template-name>
Customize: Edit the generated files to match your brand

Dependency Handling

The CLI automatically:

Detects which dependencies are required for your chosen template
Checks if they're already installed in your project
Prompts you to install missing dependencies
Provides the exact install command for your package manager

Usage Examples

Example 1: Quick Setup

# Navigate to your Next.js project
cd my-nextjs-app

# Install 404lab globally
npm install -g 404lab

# Add a simple 404 page
404lab add simple

# Start your dev server
npm run dev

# Visit http://localhost:3000/nonexistent to see your new 404 page

Example 2: Using npx (No Installation)

# Add a modern animated 404 page
npx 404lab add modern

# The CLI will:
# ✅ Create app/not-found.tsx
# ✅ Create components/404/ModernPage.tsx
# ✅ Check for required dependencies
# ✅ Prompt to install if missing

Example 3: Browse and Choose

# List all available templates
404lab list

# Pick one and install
404lab add terminal

# Test it out
npm run dev

Example 4: Switch Templates

# Remove current template
404lab remove

# Add a different one
404lab add particles

# Install dependencies when prompted
pnpm install @tsparticles/engine @tsparticles/react @tsparticles/slim

Example 5: Custom Path (Advanced)

# Add template to custom location
404lab add snow --path ./app/error-pages

# Note: You'll need to manually wire it up in this case

Troubleshooting

"Not a Next.js project"

Problem: CLI can't detect Next.js configuration.

Solution:

# Make sure you're in the project root
cd path/to/your/nextjs-project

# Verify next.config.js or next.config.ts exists
ls next.config.*

"Template already exists"

Problem: A 404 page is already installed.

Solution:

# Option 1: Remove existing first
404lab remove
404lab add <new-template>

# Option 2: Force overwrite
404lab add <template> --force

"Missing dependencies"

Problem: Template requires packages not installed.

Solution:

# The CLI will show you what's missing
# Install them with your package manager

# For npm:
npm install @tsparticles/engine @tsparticles/react @tsparticles/slim

# For pnpm:
pnpm install @tsparticles/engine @tsparticles/react @tsparticles/slim

# For yarn:
yarn add @tsparticles/engine @tsparticles/react @tsparticles/slim

"Permission denied"

Problem: Can't write files to the project directory.

Solution:

# On Unix/Mac, check permissions
ls -la app/

# Fix permissions if needed
chmod -R 755 app/

# Or run with sudo (not recommended)
sudo 404lab add <template>

"Command not found: 404lab"

Problem: CLI not installed globally or not in PATH.

Solution:

# Option 1: Use npx instead
npx 404lab add <template>

# Option 2: Install globally
npm install -g 404lab

# Option 3: Check global bin path
npm config get prefix
# Add the bin folder to your PATH

Advanced Usage

Programmatic API

You can also use 404lab programmatically in your Node.js scripts:

const { add404Page, listTemplates, remove404Page } = require("404lab");

// Add a template
await add404Page("modern", {
  path: "./app",
  force: true,
});

// List templates
const templates = await listTemplates();
console.log(templates);

// Remove template
await remove404Page({
  keepDeps: false,
});

Custom Templates

To create your own templates:

Fork the 404lab repository
Add your template to templates/
Update the template registry
Submit a pull request

CLI Features Roadmap

Interactive template picker with previews
Custom theme configuration (colors, fonts)
Template preview in terminal
Multi-template support (different templates for different routes)
Template customization wizard
Export templates to standalone components
Cloud template marketplace

Features

Core Features

19+ Premium 404 Components: Carefully crafted, unique designs including Among Us, Blue Glitch, Bug Game, Google-inspired, macOS-style, Modern, Particles, Poet, Retro TV, Snow, Stone Age, Stranger Things, Terminal, Vercel-style, and more
Interactive Previews: Live component previews with real-time code viewing
Comprehensive Documentation: Detailed MDX-based documentation for each component
Native Dark Mode: Beautifully optimized dark interface by default
Responsive Design: Mobile-first, fully responsive components
Particle Effects: Advanced particle systems with TSParticles

Platform Features

User Authentication: Secure authentication with Better Auth and Google OAuth
User Dashboard: Personalized user profiles and component management
Payment Integration: Paddle integration for premium features
AI Assistant (Coming Soon): OpenAI-powered assistant for customization (Premium feature)
Database: PostgreSQL with Prisma ORM
Type Safety: Full TypeScript coverage across the entire codebase

Developer Experience

MDX Documentation: Rich, interactive documentation
Component Props Tables: Auto-generated props documentation
CLI Commands: Quick component installation via CLI
Code Snippets: Copy-paste ready code examples
Tabbed Code Blocks: Multiple implementation examples
Version Control: Git-based workflow with proper .gitignore

Tech Stack

Frontend

Next.js 16.1 - React framework with App Router
React 19 - UI library
TypeScript 5 - Type safety
Tailwind CSS 4 - Utility-first CSS
TSParticles - Particle effects
Lucide React - Icon library
next-themes - Theme management (Forced Dark Mode)

Backend & Database

Prisma - Modern ORM
PostgreSQL - Database (Neon)
Better Auth - Authentication
Paddle - Payment processing

AI & Content

OpenAI - AI integration
MDX - Markdown with JSX
AI SDK - AI toolkit

Development Tools

pnpm - Fast, disk space efficient package manager
ESLint - Code linting
PostCSS - CSS processing

Quick Start

Get started in 60 seconds:

# Clone the repository
git clone https://github.com/yourusername/404-lab.git
cd 404-lab

# Install dependencies
pnpm install

# Set up environment variables
cp .env.paddle.example .env.local
# Edit .env.local with your credentials

# Run database migrations
pnpm prisma migrate dev

# Start the development server
pnpm dev

Open http://localhost:3000 to see your application.

Installation

Prerequisites

Ensure you have the following installed:

Node.js 18.0 or higher
pnpm 8.0 or higher
PostgreSQL database (or use Neon)
Git

Step-by-Step Installation

Clone the Repository

git clone https://github.com/yourusername/404-lab.git
cd 404-lab

Install Dependencies
```
pnpm install
```
Environment Setup

Create a .env.local file in the root directory:
```
cp .env.paddle.example .env.local
```
Fill in the required environment variables (see Configuration).

Database Setup

# Generate Prisma Client
pnpm prisma generate

# Run migrations
pnpm prisma migrate dev

# (Optional) Seed the database
node scripts/check-users.js

Start Development Server
```
pnpm dev
```

Configuration

Environment Variables

Create a .env.local file with the following variables:

Core Configuration

# Application URLs
NEXT_PUBLIC_API_URL=http://localhost:3000
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3000/api/auth

Authentication

# Better Auth
BETTER_AUTH_SECRET=your_secret_key_here

# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

Database

# PostgreSQL Connection String
DATABASE_URL=postgresql://user:password@host:port/database?sslmode=require

AI Integration

# OpenAI API Key
OPENAI_API_KEY=sk-proj-your_openai_api_key

Payment Processing (Paddle)

# Paddle Configuration
NEXT_PUBLIC_PADDLE_ENVIRONMENT=sandbox
NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=your_paddle_client_token
NEXT_PUBLIC_PADDLE_PRICE_ID=your_paddle_price_id

# Paddle Server-side
PADDLE_API_KEY=your_paddle_api_key
PADDLE_WEBHOOK_SECRET_KEY=your_paddle_webhook_secret

Obtaining API Keys

OpenAI API Key

Visit OpenAI Platform
Create an account or sign in
Navigate to API Keys section
Generate a new secret key

Google OAuth

Go to Google Cloud Console
Create a new project
Enable Google+ API
Create OAuth 2.0 credentials
Add authorized redirect URIs

Paddle Integration

Sign up at Paddle
Access your dashboard
Get your client token and API key
Set up webhook endpoint

Database (Neon)

Sign up at Neon
Create a new project
Copy the connection string

Available Components

Component Library

Component	Style	Interactivity	Difficulty
SimplePage	Minimalist	Static	Beginner
ModernPage	Contemporary	Animated	Beginner
Google	Brand-inspired	Static	Beginner
Vercel	Brand-inspired	Animated	Intermediate
GeeksforGeeks	Educational	Interactive	Intermediate
Terminal	Developer	Interactive CLI	Intermediate
MacOs	System UI	Interactive	Intermediate
RetroTv	Vintage	Animated	Intermediate
BlueGlitch	Glitch effect	Animated	Advanced
Particles	Effects	Interactive	Advanced
Snow	Seasonal	Particle system	Advanced
Poet	Artistic	Dynamic text	Intermediate
StoneAge	Themed	Illustrated	Intermediate
StrangerThings	Pop culture	Animated	Advanced
AmongUs	Game-inspired	Interactive	Advanced
BugGame	Playful	Game mechanics	Advanced
Void	Abstract	3D effects	Advanced
TabDisplay	Utility	Multi-tab	Intermediate
TabDisplayDynamic	Utility	Dynamic content	Advanced

Component Features

Each component includes:

Full TypeScript types
Customizable props
Responsive design
Accessibility features
Native dark mode aesthetic
Documentation with examples
Copy-paste ready code

Usage

Basic Implementation

Choose a Component

Browse components at http://localhost:3000/components

View Documentation

http://localhost:3000/components/[component-slug]

Copy the Code

Each component page includes:
- Live preview
- Installation instructions
- Props documentation
- Usage examples

Example: Using the SimplePage Component

import { SimplePage } from "@/components/404/SimplePage";

export default function NotFound() {
  return (
    <SimplePage
      title="Page Not Found"
      message="The page you're looking for doesn't exist."
      showHomeButton={true}
    />
  );
}

Customization

All components accept props for customization:

import { ModernPage } from "@/components/404/ModernPage";

export default function Custom404() {
  return (
    <ModernPage
      title="Oops! Lost in Space"
      subtitle="This page has drifted into the void"
      primaryColor="#FF6B6B"
      buttonText="Return to Earth"
      onButtonClick={() => router.push("/")}
    />
  );
}

Advanced Usage with Particles

import { Particles } from "@/components/404/Particles";

export default function AnimatedNotFound() {
  return (
    <div className="min-h-screen">
      <Particles
        particleCount={100}
        particleColor="#ffffff"
        backgroundColor="#000000"
      />
    </div>
  );
}

Project Structure

404-lab/
├── app/                          # Next.js App Router
│   ├── (site)/                   # Public site routes
│   │   ├── components/           # Component showcase
│   │   ├── pricing/              # Pricing page
│   │   └── user/                 # User dashboard
│   ├── actions/                  # Server actions
│   ├── ai/                       # AI assistant
│   ├── api/                      # API routes
│   │   └── auth/                 # Auth endpoints
│   ├── signin/                   # Sign in page
│   ├── signup/                   # Sign up page
│   └── forgot-password/          # Password reset
│
├── components/                   # React components
│   ├── 404/                      # 404 components library
│   │   ├── AmongUs.tsx
│   │   ├── BlueGlitch.tsx
│   │   ├── Terminal.tsx
│   │   └── ...                   # 19+ components
│   ├── auth/                     # Auth forms
│   ├── content/                  # Content components
│   ├── docs/                     # MDX documentation
│   ├── Landing/                  # Landing page
│   ├── site/                     # Site layout
│   └── ui/                       # UI primitives
│
├── lib/                          # Utility libraries
│   ├── auth.ts                   # Auth configuration
│   ├── auth-client.ts            # Auth client
│   ├── db.ts                     # Database client
│   ├── paddle.ts                 # Paddle integration
│   └── 404-components.ts         # Component registry
│
├── prisma/                       # Database schema
│   ├── schema.prisma             # Prisma schema
│   └── migrations/               # Database migrations
│
├── server/                       # Server utilities
│   └── ai.ts                     # AI configuration
│
├── types/                        # TypeScript types
│   ├── mdx.d.ts                  # MDX types
│   └── raw.d.ts                  # Raw loader types
│
├── public/                       # Static assets
├── scripts/                      # Utility scripts
├── .env.local                    # Environment variables
├── next.config.ts                # Next.js config
├── tailwind.config.ts            # Tailwind config
├── tsconfig.json                 # TypeScript config
└── package.json                  # Dependencies

Authentication

Features

Email/Password authentication
Google OAuth integration
Password reset functionality
Session management
Protected routes
User profiles

Implementation

The app uses Better Auth for authentication:

// lib/auth.ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: prisma,
  emailAndPassword: {
    enabled: true,
  },
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    },
  },
});

Protected Routes

// middleware.ts (example)
import { authMiddleware } from "@/lib/auth";

export default authMiddleware({
  publicRoutes: ["/", "/components", "/pricing"],
  protectedRoutes: ["/user", "/dashboard"],
});

Payments Integration

Paddle Setup

The application integrates Paddle for payment processing:

Sandbox Environment: Test payments without real charges
Production Environment: Live payment processing
Webhook Handling: Automatic subscription management
Price IDs: Configure product pricing

Implementation

// lib/paddle.ts
import { Paddle } from "@paddle/paddle-node-sdk";

export const paddle = new Paddle(process.env.PADDLE_API_KEY);

// Usage
await paddle.prices.get(priceId);

Webhook Endpoint

POST /api/paddle-webhook

Handles subscription events:

subscription.created
subscription.updated
subscription.canceled

AI Integration (Coming Soon)

Planned Features

Component customization assistant
Code generation
Natural language queries
Streaming responses

Usage

The AI assistant will be available at /ai (currently in development):

// server/ai.ts
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

export async function generateComponent(prompt: string) {
  const result = await generateText({
    model: openai("gpt-4-turbo"),
    prompt: `Generate a 404 component: ${prompt}`,
  });

  return result.text;
}

Database

Schema

The application uses Prisma with PostgreSQL:

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  image     String?
  createdAt DateTime @default(now())

  // Paddle integration
  customerId       String?
  subscriptionId   String?
  subscriptionStatus String?
}

Migrations

# Create a new migration
pnpm prisma migrate dev --name migration_name

# Apply migrations
pnpm prisma migrate deploy

# Reset database
pnpm prisma migrate reset

# Open Prisma Studio
pnpm prisma studio

Deployment

Vercel (Recommended)

Push to GitHub

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/404-lab.git
git push -u origin main

Deploy to Vercel
- Visit vercel.com
- Import your repository
- Add environment variables
- Deploy
Configure Environment

Add all environment variables from .env.local to Vercel:
- Go to Project Settings → Environment Variables
- Add each variable
- Redeploy

Other Platforms

Docker

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

EXPOSE 3000
CMD ["npm", "start"]

VPS Setup

Install Node.js and pnpm
Clone repository
Set environment variables
Build: pnpm build
Start: pnpm start
Use PM2 for process management

Contributing

We welcome contributions! Here's how you can help:

How to Contribute

Fork the Repository

git clone https://github.com/yourusername/404-lab.git

Create a Branch

git checkout -b feature/your-feature-name

Make Changes
- Add new 404 components
- Improve existing components
- Fix bugs
- Update documentation

Commit Your Changes

git commit -m "feat: add amazing new 404 component"

Push and Create PR

git push origin feature/your-feature-name

Adding New Components

Create component in components/404/YourComponent.tsx
Add MDX documentation in components/docs/yourcomponent.mdx
Register in lib/404-components.ts
Add to component showcase
Update README

Code Standards

Use TypeScript for all new code
Follow existing code style
Write meaningful commit messages
Add JSDoc comments
Test your changes
Update documentation

License

This project is licensed under the MIT License. See the LICENSE file for details.

MIT License

Copyright (c) 2026 404 Lab

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

Support

Get Help

Documentation: Full documentation
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@404lab.com

Community

Discord: Join our community server
Twitter: @404lab
Blog: Latest updates and tutorials

Roadmap

Q1 2026

10 new component designs
Component builder UI
A/B testing framework
Analytics integration

Q2 2026

Vue.js support
Svelte support
CLI tool for component installation
Component marketplace

Q3 2026

Mobile app
Advanced animations
3D components
Video backgrounds

Acknowledgments

Built with love using:

Next.js - The React Framework
Vercel - Deployment platform
Better Auth - Authentication
Prisma - Database ORM
Tailwind CSS - Styling
TSParticles - Particle effects

Special thanks to all contributors and the open-source community.

Website • Documentation • Components • Pricing

Made with ❤️ by developers, for developers

⭐ Star us on GitHub — it motivates us a lot!

Name		Name	Last commit message	Last commit date
Latest commit History 70 Commits
app		app
components		components
lib		lib
prisma		prisma
public		public
scripts		scripts
server		server
types		types
.env.example		.env.example
.gitignore		.gitignore
.hintrc		.hintrc
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
mdx-components.tsx		mdx-components.tsx
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
postcss.config.mjs		postcss.config.mjs
prisma.config.ts		prisma.config.ts
proxy.ts		proxy.ts
tsconfig.json		tsconfig.json

License

shreeteja172/404Lab

Folders and files

Latest commit

History

Repository files navigation

404 Lab

Table of Contents

Overview

Why 404 Lab?

CLI Tool

404Lab CLI - Generate Custom 404 Pages Instantly

Overview

Key Features

Installation

Global Installation (Recommended)

Use with npx (No Installation)

Requirements

Commands

404lab add <template>

404lab list

404lab remove

Available Templates

How It Works

File Placement

Template Selection

Dependency Handling

Usage Examples

Example 1: Quick Setup

Example 2: Using npx (No Installation)

Example 3: Browse and Choose

Example 4: Switch Templates

Example 5: Custom Path (Advanced)

Troubleshooting

"Not a Next.js project"

"Template already exists"

"Missing dependencies"

"Permission denied"

"Command not found: 404lab"

Advanced Usage

Programmatic API

Custom Templates

CLI Features Roadmap

Features

Core Features

Platform Features

Developer Experience

Tech Stack

Frontend

Backend & Database

AI & Content

Development Tools

Quick Start

Installation

Prerequisites

Step-by-Step Installation

Configuration

Environment Variables

Core Configuration

Authentication

Database

AI Integration

Payment Processing (Paddle)

Obtaining API Keys

OpenAI API Key

Google OAuth

Paddle Integration

Database (Neon)

Available Components

Component Library

Component Features

Usage

Basic Implementation

Example: Using the SimplePage Component

Customization

Advanced Usage with Particles

Project Structure

Authentication

Features

Implementation

`404lab add <template>`

`404lab list`

`404lab remove`

Packages