NeoChyrp

A modern, modular, and extensible blogging engine. NeoChyrp is a complete rebuild of the classic Chyrp blogging engine, designed from the ground up for performance, security, and an excellent developer experience.

It is built with a powerful tech stack including Next.js 15 (App Router), TypeScript, Tailwind CSS, and Prisma, with Supabase for authentication and database hosting.

Features

NeoChyrp comes packed with features that make it a powerful and flexible platform for any kind of blog or publication.

• Content Management:
  • Feathers: Create diverse content with different "Feathers" (post types) like Text, Photo, Video, Audio, Quotes, Links, and Uploader (multi-file/gallery).
  • WYSIWYG Editor: A modern Markdown editor for writing content.
  • Tagging & Categorization: Organize your posts with tags and nested categories. Public tags page supports fuzzy search and highlighting.
• Community & Interaction:
  • Comments: A full-featured, threaded commenting system.
  • Likes: Allow users to like and engage with posts.
  • Webmentions: A core part of the IndieWeb, allowing for rich interactions between blogs.
• Extensibility:
  • Modular Architecture: A robust, event-driven module system allows for easy extension and customization.
  • Permissions: Fine-grained, role-based access control (RBAC) for users, groups, and permissions.
  • Sample Content: Example payloads for every feather type are provided in docs/FEATHER_SAMPLE_CONTENT.md for easy onboarding and testing.
• Technical Features:
  • API-First Design: A comprehensive API for all major functionalities.
  • Database Migrations: Database schema management with Prisma Migrate.
  • Authentication: Secure authentication powered by Supabase.
  • Asset Delivery: All uploaded assets (images, audio, video, files) are delivered via /api/assets/:id for consistent, public access across all feathers.
  • Upload Validation: Asset uploads are strictly validated by type and size per feather, with clear error messages and .env-configurable limits.

Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript (strict)
• Styling: Tailwind CSS
• ORM: Prisma
• Database: PostgreSQL (via Supabase)
• Authentication: Supabase Auth

Architecture

NeoChyrp is built on a modern, modular architecture that emphasizes separation of concerns and developer ergonomics.

• Domain-Driven Design (DDD): Each feature is treated as a "module" with its own domain, application, infrastructure, and UI layers.
• Event-Driven: Modules communicate through an event bus, keeping them decoupled and making the system highly extensible.
• API-First: The majority of functionality is exposed via a RESTful API, allowing for flexible client implementations.

Directory Structure

neo-chyrp/
├── prisma/            # Database schema, migrations, and seed script
├── scripts/           # Helper scripts for bootstrapping the application
├── src/
│   ├── app/           # Next.js App Router routes (RSC)
│   ├── components/    # Shared UI components
│   ├── feathers/      # Feather (post type) definitions and renderers
│   ├── lib/           # Core infrastructure (DB, auth, events, etc.)
│   ├── modules/       # Feature modules (comments, likes, etc.)
│   └── styles/        # Global styles
└── ...

Getting Started

Follow these instructions to get NeoChyrp up and running on your local machine for development and testing purposes.

Prerequisites

• Node.js (v20.x or later)
• npm (v10.x or later)
• A Supabase account for database and authentication.

Installation

1. Clone the repository:

   git clone https://github.com/your-username/neo-chyrp.git
   cd neo-chyrp

2. Install dependencies:

   npm install

3. Set up environment variables: Copy the .env.example file to a new file named .env and fill in the required values.

   cp .env.example .env

4. Run database migrations: This will apply the database schema to your Supabase database.

   npm run db:migrate

5. Seed the database: This will populate the database with some initial data (e.g., an admin user, default settings).

   npm run db:seed

6. Run the development server:

   npm run dev

   The application should now be running at http://localhost:3000.

Asset Delivery Note

All uploaded assets (images, audio, video, files) are served via /api/assets/:id for public access. If you encounter 403 errors, ensure your Supabase storage bucket is public and you are using asset IDs (not raw URLs) in your content. See the docs/FEATHER_SAMPLE_CONTENT.md for examples.

One-Command Bootstrap

For convenience, you can use the helper scripts in the scripts/ directory to perform all the setup steps at once.

• macOS/Linux:

  ./scripts/start.sh

• Windows (PowerShell):

  ./scripts/start.ps1

• Windows (CMD):

  scripts\\start.cmd

Configuration

All configuration is done via environment variables. See the .env.example file for a full list of available options. The maximum upload size for assets is controlled by NEXT_PUBLIC_MAX_UPLOAD_BYTES (in bytes).

Variable	Description
NEXT_PUBLIC_APP_NAME	The name of your application.
NEXT_PUBLIC_APP_URL	The public URL of your application.
NEXT_PUBLIC_SUPABASE_URL	Your Supabase project URL.
NEXT_PUBLIC_SUPABASE_ANON_KEY	Your Supabase anonymous public key.
SUPABASE_SERVICE_ROLE_KEY	Your Supabase service role key (should be kept secret).
DATABASE_URL	The connection string for your Supabase database (with connection pooling).
DIRECT_URL	The direct connection string for your Supabase database (used for migrations).
NEXTAUTH_SECRET	A secret key for NextAuth.
NEXTAUTH_URL	The URL for NextAuth.
ENCRYPTION_KEY	A 32-byte key for encryption.
JWT_SIGNING_KEY	A key for signing JWTs.

License

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