{"id":18223921,"url":"https://github.com/hunterashaw/cms-worker","last_synced_at":"2025-06-11T16:34:54.171Z","repository":{"id":260814774,"uuid":"882394013","full_name":"hunterashaw/cms-worker","owner":"hunterashaw","description":"A minimal, headless CMS (with live preview) that can be effortlessly self-hosted on Cloudflare Workers for free.","archived":false,"fork":false,"pushed_at":"2025-02-15T18:12:56.000Z","size":291,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T15:52:29.258Z","etag":null,"topics":["cloudflare-workers","cms","jsonschema","reactjs"],"latest_commit_sha":null,"homepage":"https://cms-worker.shaw-hunter-a.workers.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hunterashaw.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-02T18:02:28.000Z","updated_at":"2025-02-28T02:53:48.000Z","dependencies_parsed_at":"2024-11-02T19:21:26.399Z","dependency_job_id":"b12568d5-51d6-49a4-b9dc-258b93e807f8","html_url":"https://github.com/hunterashaw/cms-worker","commit_stats":null,"previous_names":["hunterashaw/cms-worker"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunterashaw%2Fcms-worker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunterashaw%2Fcms-worker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunterashaw%2Fcms-worker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunterashaw%2Fcms-worker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hunterashaw","download_url":"https://codeload.github.com/hunterashaw/cms-worker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248269465,"owners_count":21075783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare-workers","cms","jsonschema","reactjs"],"created_at":"2024-11-04T01:05:28.367Z","updated_at":"2025-06-11T16:34:54.164Z","avatar_url":"https://github.com/hunterashaw.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Worker CMS: A Cloudflare Headless CMS\n\nWorker CMS is a minimal, yet powerful, headless Content Management System designed to run seamlessly on [Cloudflare Workers](https://workers.cloudflare.com/), leveraging the global Cloudflare network for speed and scalability. It's built to be effortlessly self-hosted, offering a free tier-friendly solution for managing your content.\n\n🔗 **[Live demo (read-only) here!](https://cms-worker.shaw-hunter-a.workers.dev/)**\n\n## ✨ Features\n\nWorker CMS provides a comprehensive suite of tools for content management, all running on the edge:\n\n*   👤 **User Management**:\n    *   Secure passwordless authentication.\n    *   API token support for programmatic access.\n    *   Email verification via [Resend](https://resend.com/) (with console log fallback for development).\n*   🧱 **Data Modeling with JSON Schema**:\n    *   Define your content structures using the flexible [JSON Schema](https://json-schema.org/) standard.\n    *   Data is stored reliably in [Cloudflare D1](https://www.cloudflare.com/developer-platform/products/d1/), Cloudflare's native serverless SQL database.\n*   🗂️ **File Storage**:\n    *   Integrated file management for hosting images, documents, and other assets.\n    *   Utilizes [Cloudflare R2](https://www.cloudflare.com/developer-platform/products/r2/) for scalable and cost-effective object storage.\n*   ✍️ **Rich Markdown Editor**:\n    *   Intuitive content creation with the [MDX Editor](https://mdxeditor.dev/), supporting common formatting, links, and image uploads directly to R2.\n*   👀 **Live Preview**:\n    *   Instantly preview your content changes within your own websites or applications via an iframe and `window.postMessage` communication.\n*   🔌 **Extensible Plugin System**:\n    *   Tailor the CMS to your exact needs by creating or integrating plugins.\n    *   Plugins can:\n        *   Add new data models and associated UI in the admin panel.\n        *   Introduce custom server-side routes and middleware.\n        *   Integrate with third-party services and APIs.\n*   🛍️ **Example: BigCommerce Plugin Included**:\n    *   Demonstrates the power of the plugin system.\n    *   Allows Worker CMS to be installed as an app within a BigCommerce store.\n    *   Handles OAuth2 installation and token management.\n    *   Adds BigCommerce-specific models (e.g., Products, Configuration) to the CMS.\n    *   Provides a foundation for syncing and managing BigCommerce data through Worker CMS.\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n*   [Node.js](https://nodejs.org/) (LTS version recommended) and npm.\n*   A [Cloudflare account](https://dash.cloudflare.com/sign-up).\n\n### Setup\n\n1.  **Clone or Download**:\n    Get the project code:\n    ```bash\n    git clone https://github.com/your-username/cms-worker.git # Or download the ZIP\n    cd cms-worker\n    ```\n\n2.  **Install Dependencies**:\n    ```bash\n    npm install\n    ```\n\n3.  **Database Migration**:\n    Set up your Cloudflare D1 database tables. You'll need `wrangler` logged in (`npx wrangler login`).\n    ```bash\n    npx wrangler d1 migrations apply YOUR_DATABASE_NAME --local # For local development\n    # or\n    # npx wrangler d1 migrations apply YOUR_DATABASE_NAME --remote # For production\n    ```\n    *Ensure your `wrangler.toml` has the correct D1 binding and database ID.*\n\n4.  **Local Development**:\n    Start the development server (usually on `http://localhost:3000`):\n    ```bash\n    npm start\n    ```\n    During local development, user verification codes will be printed to the console if a Resend API key is not configured.\n\n## 🛠️ Configuration \u0026 Development\n\n### Core Configuration (`wrangler.toml`)\n\nYour `wrangler.toml` file is crucial for binding Cloudflare services:\n\n*   **D1 Database**: For storing content and user data.\n*   **R2 Bucket**: For file storage.\n*   **Environment Variables**:\n    *   `RESEND_KEY`: (Optional) Your API key from Resend for sending verification emails.\n    *   `DEMO`: Set to `\"true\"` to enable read-only demo mode.\n    *   `JWT_SECRET`: A strong secret for signing JWTs (used by core auth).\n    *   For the BigCommerce Plugin:\n        *   `BIGCOMMERCE_CLIENT_ID`: Your BigCommerce app's Client ID.\n        *   `BIGCOMMERCE_CLIENT_SECRET`: Your BigCommerce app's Client Secret.\n\n### Defining Data (Models)\n\n*   Models are defined using JSON Schema. Core models can be structured in `src/models.ts` (or a similar configuration file).\n*   Plugins, like the included BigCommerce plugin (`src/plugins/big-commerce/app.tsx`), can dynamically register their own models with the CMS.\n*   **Schema Rules**:\n    *   The root `schema` must be an `object`.\n    *   Supported property types: `string`, `number`, `boolean`, `array`, `object`.\n    *   Properties can have `title`, `description`, and `default` values.\n    *   Strings can have `format: 'date-time'` or `format: 'markdown'`.\n    *   Arrays typically use `items: { type: 'object', properties: { ... } }` or `items: { anyOf: [...] }` for polymorphic arrays (block-style content).\n\n### Markdown Editor\n\nString properties with `format: 'markdown'` utilize the MDX Editor, offering a rich text editing experience with support for headings, lists, emphasis, links, and image uploads.\n\n### Live Preview\n\nModels can enable live preview by defining a `previewURL` function in their configuration:\n`previewURL?: (document: { model: string; name: string; value: any }) =\u003e string | undefined;`\nThis function should return the URL to load in an iframe. The CMS will `postMessage` updates to this iframe as the document changes. See `public/test.html` for a basic JavaScript example.\n\n### Building Plugins\n\nPlugins are the primary way to extend Worker CMS. A typical plugin might have:\n\n*   **Server-Side Logic (`server.ts` or similar)**:\n    *   Located within a plugin directory (e.g., `src/plugins/my-plugin/server.ts`).\n    *   Can add new routes to the main worker router (`import { router } from '../../worker'`).\n    *   Can add custom middleware.\n    *   Example: `src/plugins/big-commerce/server.ts` handles BigCommerce installation and API authentication.\n*   **Client-Side Logic (`app.tsx` or similar)**:\n    *   Located within a plugin directory (e.g., `src/plugins/my-plugin/app.tsx`).\n    *   Can register new models with the CMS frontend.\n    *   Can provide custom editor components or UI elements.\n    *   Example: `src/plugins/big-commerce/app.tsx` registers product and configuration models.\n\n### Key Development Files\n\n*   **Backend Entry**: `src/worker.ts` (main Cloudflare Worker script).\n*   **Frontend Core**: `src/components/app.tsx` (main React application).\n*   **Models Configuration**: Typically `src/models.ts` for core models.\n*   **Plugin Directory**: `src/plugins/` for individual plugin modules.\n\n## ☁️ Deployment\n\n1.  **Configure `wrangler.toml`**:\n    Ensure all necessary bindings (D1, R2) and environment variables (see \"Core Configuration\") are set for your production environment.\n\n2.  **Deploy to Cloudflare**:\n    ```bash\n    npm run deploy\n    ```\n\nThis will publish your Worker CMS instance to your Cloudflare account, making it accessible via the configured routes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunterashaw%2Fcms-worker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhunterashaw%2Fcms-worker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunterashaw%2Fcms-worker/lists"}