Next.js JSON CMS

A powerful, git-based JSON Content Management System for Next.js applications with real-time preview capabilities. Supports both App Router and Pages Router architectures.

🚀 What is Next.js JSON CMS?

Next.js JSON CMS is a lightweight, file-based content management system that allows you to:

• Manage JSON content through a beautiful web interface
• Real-time preview changes as you edit
• Git-based versioning for content tracking
• Schema validation to ensure content consistency
• Monaco Editor for advanced JSON editing with syntax highlighting
• Zero database setup - everything is file-based

🎯 Why Use This Package?

Perfect For:

• Static websites that need dynamic content
• JAMstack applications requiring content management
• Developer-friendly projects where content is code
• Small to medium projects that don't need complex CMS
• Teams that prefer Git workflows for content
• Prototyping and quick content iteration

Key Benefits:

• ✅ No Database Required - Everything stored as JSON files
• ✅ Git Integration - Track content changes with version control
• ✅ Real-time Updates - See changes instantly on your website
• ✅ Developer-Friendly - Familiar JSON format and Git workflow
• ✅ Lightweight - Minimal overhead, fast performance
• ✅ Schema Validation - Prevent content structure errors
• ✅ Both Router Types - Works with App Router and Pages Router

📋 Prerequisites

• Node.js >= 16.0.0
• npm or yarn
• Basic knowledge of Next.js and JSON

🛠 Installation & Setup

Quick Start

# Install globally
npm install -g next-json-cms

# Or use npx (recommended)
npx next-json-cms init my-cms-project

# Navigate to your project
cd my-cms-project

# Start the development server
npm run dev

Interactive Setup

The CLI will prompt you to choose:

1. Router Type: App Router or Pages Router
2. Directory Structure: With or without src directory
3. Git Configuration: Username and email for commits

npx next-json-cms init

? What would you like to name your project? › my-cms-project
? Which router would you like to use? › 
❯ App Router (recommended)
  Pages Router

? Would you like to use the src directory? › 
❯ Yes (recommended)
  No

? Git username for commits (optional) › your-username
? Git email for commits (optional) › [email protected]

🏗 Project Structure

After initialization, your project will have:

my-cms-project/
├── content/                    # JSON content files
│   ├── example.json           # Sample content
│   └── schema/                # JSON schemas for validation
│       └── example.schema.json
├── src/ (or root)
│   ├── components/
│   │   ├── editor/            # CMS editor components
│   │   │   ├── EditorPage.tsx
│   │   │   ├── FileTree.tsx
│   │   │   └── EditorToolbar.tsx
│   │   └── home/              # Home page components
│   │       └── ContentDisplay.tsx
│   ├── services/              # API services
│   │   ├── contentService.ts
│   │   └── gitService.ts
│   ├── store/                 # State management
│   │   └── editorStore.ts
│   └── app/ (or pages/)       # Next.js routes
│       ├── page.tsx           # Home page
│       ├── editor/
│       │   └── page.tsx       # CMS editor
│       └── api/               # API routes
│           ├── content/
│           └── git/
└── package.json

🎮 Usage

1. Starting the CMS

# Start development server
npm run dev

# Or use the CLI command
npx next-json-cms start

Your CMS will be available at:

• Home Page: http://localhost:3000
• CMS Editor: http://localhost:3000/editor

2. Managing Content

Through the Web Interface:

1. Navigate to /editor
2. Select a JSON file from the file tree
3. Edit content using the Monaco editor
4. Save to commit changes to Git

Programmatically:

// In your Next.js pages/components
import { useEffect, useState } from 'react';

function MyComponent() {
  const [content, setContent] = useState(null);

  useEffect(() => {
    fetch('/api/content?file=example.json')
      .then(res => res.json())
      .then(data => setContent(data));
  }, []);

  return (
    <div>
      <h1>{content?.title}</h1>
      <p>{content?.description}</p>
    </div>
  );
}

3. Creating Custom Content

1. Add new JSON file in the content/ directory
2. Create corresponding schema in content/schema/ (optional)
3. Use in your components via the API

Example content file (content/blog-post.json):

{
  "title": "My Blog Post",
  "author": "John Doe",
  "publishedAt": "2024-01-15",
  "content": "This is my blog post content...",
  "tags": ["nextjs", "cms", "json"]
}

🔧 API Reference

Content API

Get Content

GET /api/content?file=example.json

Update Content

POST /api/content
Content-Type: application/json

{
  "file": "example.json",
  "content": { "title": "Updated Title" }
}

Git API

Get Git Status

GET /api/git/status

Commit Changes

POST /api/git/commit
Content-Type: application/json

{
  "message": "Update content"
}

🎨 Customization

Styling

The CMS uses Tailwind CSS by default. You can customize:

1. Global styles in globals.css
2. Component styles by modifying component files
3. Tailwind config in tailwind.config.js

Adding Features

1. Custom validators in schema files
2. Additional API routes for extended functionality
3. Custom components for specialized content types

⚠️ Limitations

Current Limitations:

• File-based only - Not suitable for large-scale content (1000+ files)
• Single user editing - No concurrent editing support
• Git dependency - Requires Git for version control features
• JSON only - No support for other content formats (Markdown, etc.)
• No asset management - Limited media/file upload capabilities
• No user authentication - Open access to CMS (add your own auth)
• No real-time collaboration - Changes aren't synced between multiple editors

Scale Considerations:

• Recommended for: <100 content files
• Performance: May slow down with >500 files
• Git history: Large files can bloat repository size

Browser Support:

• Modern browsers only (Chrome 80+, Firefox 75+, Safari 13+)
• Monaco Editor dependency requires JavaScript enabled

🔒 Security Considerations

⚠️ Important Security Notes:

1. No built-in authentication - Add your own auth middleware
2. File system access - API routes have file system permissions
3. Git operations - CMS can commit to your repository
4. Public access - Editor is publicly accessible by default

Recommended Security Measures:

// Add authentication middleware
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Add your authentication logic here
  if (request.nextUrl.pathname.startsWith('/editor')) {
    // Check authentication
    const isAuthenticated = checkAuth(request);
    if (!isAuthenticated) {
      return NextResponse.redirect(new URL('/login', request.url));
    }
  }
}

🚀 Deployment

Vercel (Recommended)

# Deploy to Vercel
npm run build
vercel --prod

Other Platforms

1. Build the project: npm run build
2. Deploy: Follow your platform's Next.js deployment guide
3. Environment: Ensure Git is available in production (if using Git features)

🔧 Troubleshooting

Common Issues:

1. React Version Conflicts

# If you see React peer dependency warnings
npm install --legacy-peer-deps

2. Git Not Initialized

# Initialize Git repository
git init
git add .
git commit -m "Initial commit"

3. File Permission Errors

# Ensure proper permissions on content directory
chmod -R 755 content/

4. Port Already in Use

# Use different port
npx next-json-cms start --port 3001

🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests (if applicable)
5. Submit a pull request

📜 License

MIT License - see LICENSE file for details.

🆘 Support

• GitHub Issues: Report bugs and request features
• Documentation: Full documentation
• Examples: Check the examples/ directory

🔮 Roadmap

Planned Features:

• [ ] Markdown support for rich content editing
• [ ] Asset management for images and files
• [ ] Multi-user support with authentication
• [ ] Content scheduling and publishing workflows
• [ ] Plugin system for extensibility
• [ ] Content templates for faster creation
• [ ] Search functionality across content
• [ ] Backup and restore features

Made with ❤️ for the Next.js community

Quick Links

• NPM Package
• GitHub Repository
• Documentation
• Examples