DOCSEARCHbyAlgolia
Submit Docs

SonicJS Documentation

repository·main·Indexed 23 days ago

https://github.com/sonicjs-org/sonicjs

An edge-native, headless CMS built on Cloudflare Workers featuring a TypeScript-first, schema-as-code approach. SonicJS provides high performance with zero cold starts, utilizing Cloudflare D1 for databases and R2 for media storage. It includes a REST API for content access, a plugin system for extensibility, and a built-in admin UI for content and plugin management.

Tokens
533.5K
Snippets
1.2K
Records
2.1K
Agent score
82%

What's inside SonicJS

  1. Overview of the Testimonials Plugin

    main

    The Testimonials plugin provides a turnkey system for managing customer reviews and testimonials. It allows you to capture author details (name, title, company), review text, and an optional 1-5 star rating. Key features include:

    • Star Ratings: Optional 1-5 star ratings with database-level validation.
    • Author Profiles: Capture name, job title, and company.
    • Publish Control: Manage testimonials in 'draft' or 'published' states with custom sort ordering.
    • REST API: A full CRUD API with built-in filtering for published status and minimum star ratings.

  2. Overview of E2E test coverage and structure

    main

    The SonicJS AI E2E suite uses Playwright to cover 390 tests across 5 browser configurations (Desktop Chrome, Firefox, Safari, Mobile Chrome, and Mobile Safari).

    Core Test Files

    • 01-health.spec.ts: API health, redirects, and 404 handling.
    • 02-authentication.spec.ts: Login, session persistence, and route protection.
    • 03-admin-dashboard.spec.ts: Dashboard layout, stats, and navigation.
    • 04-collections.spec.ts: Collection CRUD and validation.
    • 05-content.spec.ts: Content listing, filtering, and pagination.
    • 06-media.spec.ts: File uploads and media library management.
    • 07-api.spec.ts: OpenAPI spec, CORS, and error responses.
    • 08-responsive.spec.ts: Viewport testing (Mobile/Tablet/Desktop) and touch targets.
    • 09-integration.spec.ts: Full workflows (e.g., collection-to-content, media usage).

  3. Overview of the SonicJS Developer SDK

    main

    The @sonicjs-cms/sdk is an isomorphic, zero-runtime-dependency TypeScript client designed to interact with the SonicJS headless CMS API. It is compatible with browsers, Node.js, and Cloudflare Workers.

    Key features include:

    • Full CRUD Support: Read and write access for content, collections, media, and authentication.
    • Isomorphic Core: Uses native fetch with no external dependencies.
    • Type Safety: Includes a codegen CLI that generates per-collection TypeScript types from a live SonicJS instance.
    • Authentication: Supports API keys, JWT sessions, and public/anonymous reads.

  4. Overview of SonicJS Documentation Structure

    main

    The SonicJS documentation is organized into several key sections to guide developers from initial setup to advanced customization:

    • Getting Started: Includes the Landing Page, Quickstart (60-second setup), and Installation (Prerequisites, NPM/PNPM, Cloudflare account, and Environment configuration).
    • Core Concepts: Covers Architecture (Cloudflare Workers, request lifecycle, middleware), Collections (field types, schema examples), Caching (three-tier system, invalidation), and Authentication (JWT, RBAC, permissions).
    • Developer Guide: Provides API Reference (endpoints, request/response, rate limiting), Database (D1, Drizzle ORM, migrations), Templating (Handlebars-like syntax), and Routing & Middleware.
    • Plugin System: Details Plugin Architecture, Plugin Development (hooks, extension points), and Core Plugins (Auth, Media, Cache, Database).
    • Deployment & Operations: Covers Cloudflare Workers deployment, CI/CD, and Testing (Vitest, Playwright).
    • Advanced Topics: Includes Admin Design System, Settings & Configuration, and the Workflow System.
    • Resources: Examples (Blog, E-commerce, etc.), Migration Guides, FAQ, and Community links.

  5. Overview of SonicJS Core Plugins

    main
    SonicJS includes several essential core plugins that provide fundamental functionality like authentication, media management, caching, and database administration. These plugins are automatically installed and configured during the SonicJS setup process. They follow the same plugin architecture as custom plugins, allowing them to serve as reference implementations for developers building their own extensions.

  6. Overview of the Analytics Plugin

    main

    The Analytics plugin is a built-in feature of SonicJS core that provides two main capabilities:

    1. Custom Event Tracking: Allows you to track named events via an HTTP API (single or batch). Events are stored as analytics_event documents and can be queried by event name, category, user, session, or date range.
    2. Request Monitoring Dashboard: An admin dashboard located at /admin/analytics that displays metrics from the last 24 hours, including request totals, unique IPs, average response time, error counts, and top URLs. This dashboard is sourced from system_logs.

    Note: The dashboard metrics are sourced from system_logs and are separate from the custom events stored via the API.

  7. Overview of available SonicJS Plugins

    main

    SonicJS includes several core and optional plugins to extend functionality. Note that some plugins may require additional documentation as they are being actively integrated into the official docs.

    Core Plugins

    • AI Search Plugin: Provides semantic search with embeddings and RAG (Retrieval-Augmented Generation).
    • Turnstile Plugin: Integrates Cloudflare Turnstile for bot protection and CAPTCHA.
    • Workflow Plugin: Manages content workflow states, approval processes, and automation rules.
    • Analytics Plugin: For tracking usage and metrics.
    • Testimonials Plugin: For managing user testimonials.
    • Code Examples Plugin: For displaying code snippets.
    • Hello World Plugin: A basic starter plugin.
    • Design Plugin: For UI/design related features.
    • Authentication/Media/Cache: Standard core utilities.

    Optional Plugins

    • Email Templates Plugin: Manages email templates, queues, and rendering.

  8. Overview of the Code Examples Plugin

    main
    The Code Examples plugin is a system for managing code snippets and examples within SonicJS. It allows you to organize code by language and category, control visibility using publish states (draft vs. published), and manage display sequencing via sort ordering. All data is exposed through a filterable REST API and can be managed via a dedicated admin interface.

  9. Overview of SonicJS Forms

    main

    SonicJS includes an enterprise-grade forms system built on the open-source Form.io library. It is fully integrated with the headless CMS architecture, allowing for both a visual drag-and-drop builder in the admin UI and a headless JSON API for custom frontends.

    Key capabilities include:

    • Visual Builder: Accessible at /admin/forms.
    • Multi-Page Wizards: Support for step-by-step forms with progress indicators.
    • File Uploads: Integrated with Cloudflare R2 for storage.
    • Security: Optional authentication requirements, input sanitization, and audit trails (IP, user agent, timestamps).
    • Headless Support: Framework-agnostic JSON API for React, Vue, Angular, Astro, and Svelte.

  10. Overview of SonicJS Architecture

    main

    SonicJS is a TypeScript-first headless CMS designed specifically for the Cloudflare edge platform. It is built to provide high performance and low latency by running entirely on Cloudflare's global network.

    Key architectural characteristics include:

    • Edge-First: Deployment on Cloudflare's global edge network.
    • Zero Cold Starts: Utilizes V8 isolates for instant startup.
    • TypeScript-Native: Full type safety for improved developer experience.
    • Plugin-Driven: Extensible via a robust plugin system.
    • Performance-Optimized: Employs a three-tier caching system for sub-millisecond responses.

  11. Compare SonicJS support tiers

    main

    SonicJS is 100% MIT open source; commercial support provides response-time guarantees and dedicated channels rather than feature access. Choose a tier based on your team's production requirements:

    • Community (Free): Access to all MIT features via GitHub Issues and Discord. Best-effort community response.
    • Priority Support ($499/mo, billed annually): Includes everything in Community plus guaranteed next-business-day response, private email channel, priority security triage, and upgrade/architecture guidance. Ideal for startups running SonicJS in production.
    • Enterprise (from $2,500/mo): Includes everything in Priority plus same-business-day response (1-business-hour Sev-1 target), email + Slack channel, a named support contact, and license indemnification/IP warranty. Includes support for onboarding, migration, and security questionnaires (SOC2/vendor forms).

  12. Compare SonicJS with Strapi and Sanity

    main

    SonicJS is positioned as an edge-first, TypeScript-native CMS designed for global performance and predictable costs. Use this comparison to decide if SonicJS fits your project requirements compared to traditional alternatives:

    Choose SonicJS If:

    • Global performance is critical: Delivers under 50ms global latency with zero cold starts.
    • Predictable costs are required: Avoids the usage-based pricing surprises common in SaaS models.
    • TypeScript-native development is a priority: Built for modern developer workflows.
    • Edge-first architecture is preferred: Runs on Cloudflare infrastructure, utilizing three-tier caching (memory, KV, D1) at the edge.
    • Data ownership is valued: Open source with your own data.

    Choose Strapi If:

    • You have DevOps capacity for self-hosting.
    • You need an extensive plugin ecosystem.
    • You require full control over infrastructure and are prepared for long-term version management (e.g., managing migrations like v4 to v5).

    Choose Sanity If:

    • Real-time collaboration is an essential requirement.
    • You have a high budget and can work with GROQ.
    • You require enterprise-grade features that justify premium SaaS pricing.