@upflame/json-cms

A schema-driven CMS layer for Next.js that enables dynamic pages, modular components, SEO configuration, and navigational structures—all defined through JSON. The system exposes a clean API bridge for fetching content, making any static or hybrid Next.js app fully headless and easily maintainable.

Quick Start

# Install
npm install @upflame/json-cms

# Initialize in your Next.js project
npx json-cms init

# Start development
npm run dev

Features

• JSON-Driven Content: Define pages, components, and layouts through JSON schemas
• API-First Architecture: Standardized API layer with pluggable storage backends
• CSS-Safe Integration: Zero conflicts with existing styles through isolation strategies
• Multi-Tenant Ready: Built-in tenant isolation and context management
• Authentication & RBAC: Pluggable auth with role-based access control
• Performance Optimized: Multi-level caching and performance monitoring
• Migration System: Seamless transition from JSON files to database storage
• Plugin Architecture: Extensible through a comprehensive plugin system
• SEO Management: Centralized SEO control with optimization tools
• Security First: Input sanitization, rate limiting, and audit logging

Documentation

• Getting Started - Complete setup guide
• Integration Guide - Integrate with existing projects
• API Reference - Complete API documentation
• Plugin Development - Create custom plugins
• Multi-Tenant Setup - SaaS configuration
• Performance Guide - Optimization strategies
• Security Guide - Security best practices

Basic Usage

1. Create a Page

{
  "id": "homepage",
  "slug": "/",
  "title": "Welcome",
  "blocks": [
    {
      "id": "hero-1",
      "componentType": "Hero",
      "props": {
        "title": "Welcome to Our Platform",
        "subtitle": "Build amazing experiences",
        "ctaText": "Get Started",
        "ctaLink": "/signup"
      }
    }
  ],
  "seo": {
    "title": "Homepage - Your Company",
    "description": "Welcome to our amazing platform"
  }
}

2. Register Components

import { registerComponent } from '@upflame/json-cms';
import { Hero } from './components/Hero';

registerComponent('Hero', Hero, {
  schema: {
    title: { type: 'string', required: true },
    subtitle: { type: 'string' },
    ctaText: { type: 'string' },
    ctaLink: { type: 'string' },
  },
  metadata: {
    name: 'Hero Section',
    description: 'A hero section with title, subtitle, and CTA',
    category: 'Layout',
  },
});

3. Use the API

import { CMSClient } from '@upflame/json-cms/client';

const client = new CMSClient({
  baseURL: '/api/cms',
});

// Fetch content
const page = await client.getPage('homepage');
const blocks = await client.getBlocks({ category: 'hero' });

Configuration

// cms.config.js
module.exports = {
  provider: {
    type: 'file', // or 'database'
    config: {
      contentPath: './cms/content',
    },
  },
  cache: {
    type: 'memory', // or 'redis'
    ttl: 3600,
  },
  auth: {
    enabled: true,
    provider: 'nextauth',
  },
  tenant: {
    enabled: false, // Enable for multi-tenant
  },
  seo: {
    enabled: true,
  },
  security: {
    enabled: true,
    rateLimit: {
      enabled: true,
      requests: 100,
      window: 900000,
    },
  },
};

CLI Commands

# Project setup
json-cms init                    # Initialize CMS
json-cms scan                    # Analyze compatibility
json-cms validate               # Validate content

# Content generation
json-cms generate page --name "About"
json-cms generate component --name "ProductCard"
json-cms generate plugin --name "analytics"

# SEO & Sitemap
json-cms sitemap --base-url https://example.com  # Generate sitemap.xml

# Migration
json-cms migrate run --from file --to database
json-cms migrate status
json-cms migrate rollback

# Plugin management
json-cms plugin list
json-cms plugin install analytics-plugin
json-cms plugin activate analytics-plugin

# Maintenance
json-cms cache clear
json-cms health

Enterprise-Grade SEO

JSON CMS includes production-ready SEO features out of the box:

Automated Sitemap Generation

# Generate sitemap.xml automatically
json-cms sitemap --base-url https://yoursite.com

# Generates:
# - public/sitemap.xml with all pages
# - Homepage priority: 1.0
# - Other pages priority: 0.7
# - Auto-updates lastmod dates
# - Valid XML format for search engines

Comprehensive SEO Schema

Every page supports advanced SEO configuration:

{
  "seo": {
    "title": "Your Page Title",
    "description": "Meta description for search engines",
    "canonical": "https://yoursite.com/page",
    "robots": "index, follow",
    "keywords": ["keyword1", "keyword2"],
    "openGraph": {
      "title": "OG Title",
      "description": "OG Description",
      "url": "https://yoursite.com/page",
      "images": [{ 
        "url": "https://yoursite.com/og-image.jpg",
        "width": 1200,
        "height": 630,
        "alt": "Image description"
      }],
      "type": "website"
    },
    "twitter": {
      "card": "summary_large_image",
      "site": "@yoursite",
      "creator": "@creator",
      "title": "Twitter Title",
      "description": "Twitter Description",
      "image": "https://yoursite.com/twitter-image.jpg"
    },
    "structuredData": [
      {
        "@context": "https://schema.org",
        "@type": "Organization",
        "name": "Your Company",
        "url": "https://yoursite.com"
      }
    ],
    "alternates": {
      "languages": {
        "en": "https://yoursite.com/en/page",
        "es": "https://yoursite.com/es/page"
      }
    }
  }
}

SEO Features

• ✅ Automatic Meta Tags: Title, description, canonical, robots
• ✅ Open Graph: Full OG support for social sharing
• ✅ Twitter Cards: Summary and large image cards
• ✅ JSON-LD Structured Data: Rich snippets for search engines
• ✅ Multilingual Support: Alternate language URLs
• ✅ Sitemap Generation: Automated XML sitemap with priorities
• ✅ Dynamic Metadata: Next.js 15 metadata API integration
• ✅ Production Ready: Battle-tested for enterprise use

## Modular Exports

The package provides modular exports for different use cases:

```typescript
// Core functionality
import { CMSBoilerplate, createCMS } from '@upflame/json-cms';

// Specific modules
import { ComponentRegistry } from '@upflame/json-cms/registry';
import { AuthManager } from '@upflame/json-cms/auth';
import { CacheManager } from '@upflame/json-cms/cache';
import { PluginManager } from '@upflame/json-cms/plugins';

// Middleware
import { withCMSMiddleware } from '@upflame/json-cms/middleware';

// Configuration
import { withCMS } from '@upflame/json-cms/config';

// Testing utilities
import { createTestClient } from '@upflame/json-cms/testing';

Plugin System

Create custom plugins to extend functionality:

// plugins/analytics/index.ts
import { Plugin } from '@upflame/json-cms/plugins';

export default class AnalyticsPlugin implements Plugin {
  name = 'analytics';
  version = '1.0.0';

  async install(context) {
    // Register components, API routes, hooks
    context.registry.register('AnalyticsTracker', AnalyticsTracker);
    context.api.register('/api/analytics', analyticsHandler);
  }
}

Multi-Tenant Support

Configure for SaaS applications:

// Tenant resolution strategies
const config = {
  tenant: {
    enabled: true,
    strategy: 'domain', // domain, subdomain, path, header
    resolver: async request => {
      const host = request.headers.get('host');
      return await resolveTenantByDomain(host);
    },
  },
};

Deployment

Vercel

npm i -g vercel
vercel --prod

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Environment Variables

# Storage
CMS_PROVIDER=database
DATABASE_URL=postgresql://user:pass@host:5432/db
REDIS_URL=redis://host:6379

# Authentication
AUTH_SECRET=your-secret
NEXTAUTH_URL=https://yoursite.com

# Multi-tenant
TENANT_STRATEGY=domain

# Security
RATE_LIMIT_REQUESTS=1000
RATE_LIMIT_WINDOW=900000

Testing

import { createTestClient } from '@upflame/json-cms/testing';

describe('CMS Integration', () => {
  const client = createTestClient();

  test('should fetch page', async () => {
    const page = await client.pages.get('homepage');
    expect(page.data.title).toBe('Homepage');
  });
});

Performance

• Multi-level caching (Memory + Redis)
• Component lazy loading
• Database query optimization
• CDN integration
• Bundle size optimization
• Performance monitoring

Security

• Input validation & sanitization
• Rate limiting
• CSRF protection
• Content Security Policy
• Audit logging
• Role-based access control

Contributing

We welcome contributions! Please see our Contributing Guide.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Support

• Documentation
• GitHub Discussions
• GitHub Issues

Roadmap

• [ ] Visual page builder interface
• [ ] Advanced workflow management
• [ ] Real-time collaboration
• [ ] Enhanced analytics dashboard
• [ ] Mobile app for content management
• [ ] GraphQL API support
• [ ] Headless commerce integration

Team

UpFlame - Building the future of content management

• Victor Amit - Lead Developer & Architect

Show Your Support

If this project helped you, please consider giving it a ⭐ on GitHub!

Made with ❤️ by UpFlame