{"id":49703614,"url":"https://github.com/byline-cms/bylinecms.dev","last_synced_at":"2026-06-29T06:01:03.625Z","repository":{"id":301694496,"uuid":"1006844641","full_name":"Byline-CMS/bylinecms.dev","owner":"Byline-CMS","description":"Byline CMS - a headless, fast, and AI-Ready CMS","archived":false,"fork":false,"pushed_at":"2026-06-28T12:10:12.000Z","size":34430,"stargazers_count":33,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-28T12:17:06.723Z","etag":null,"topics":["cms","cms-framework","headless-cms"],"latest_commit_sha":null,"homepage":"https://bylinecms.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Byline-CMS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":"COPYRIGHT","agents":null,"dco":null,"cla":null}},"created_at":"2025-06-23T04:47:02.000Z","updated_at":"2026-06-27T14:17:37.000Z","dependencies_parsed_at":"2025-07-13T04:14:06.700Z","dependency_job_id":"11e3f4dd-9c5f-4d27-99bc-e3b80e87998d","html_url":"https://github.com/Byline-CMS/bylinecms.dev","commit_stats":null,"previous_names":["byline-cms/bylinecms.app","byline-cms/bylinecms.dev"],"tags_count":1324,"template":false,"template_full_name":null,"purl":"pkg:github/Byline-CMS/bylinecms.dev","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byline-CMS%2Fbylinecms.dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byline-CMS%2Fbylinecms.dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byline-CMS%2Fbylinecms.dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byline-CMS%2Fbylinecms.dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Byline-CMS","download_url":"https://codeload.github.com/Byline-CMS/bylinecms.dev/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byline-CMS%2Fbylinecms.dev/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34915002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cms","cms-framework","headless-cms"],"created_at":"2026-05-08T09:01:22.466Z","updated_at":"2026-06-29T06:01:03.619Z","avatar_url":"https://github.com/Byline-CMS.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Byline CMS\n\nA developer-friendly, open-source headless CMS — built with versioning,\neditorial workflow, and content translation as first-class concerns rather\nthan features bolted on later.\n\n\u003e Status: Byline is currently at a stable v3.x.x release. The major-version\n\u003e bumps have been driven by lockstep versioning across the publishable\n\u003e `@byline/*` packages rather than breaking redesigns — the architecture is\n\u003e settled and there are unlikely to be any major architectural changes, though\n\u003e there is still work to do.\n\u003e If you're interested in Byline, v3 is a solid base for evaluation and\n\u003e for building on.\n\n\u003cimg width=\"914\" height=\"685\" alt=\"byline-admin\" src=\"https://github.com/user-attachments/assets/1d4a6a02-b847-4e66-b8c9-9fb8964a2287\" /\u003e\n\n\u003cp style=\"font-size: 0.8rem;\"\u003e\u003cem\u003eWelcome to the Byline dashboard!\u003c/em\u003e\u003c/p\u003e\n\n## What's different\n\n- **Three pillars, not three plugins.** Versioning, editorial workflow, and\n  content translation are foundational and designed to coexist without\n  trade-offs.\n- **Universal storage (EAV-per-type).** Schemas change without migrations.\n  Documents flatten into typed `store_*` tables (text, numeric, boolean,\n  datetime, json, file, relation) addressed by a custom path notation —\n  indexable, query-friendly, and the basis for selective field loading.\n- **Immutable versioning by default.** Every change creates a new\n  UUIDv7-ordered version. \"Current\" is a pointer, not a mutation.\n- **Patch-based updates.** Clients accumulate `DocumentPatch[]`; the server\n  applies them against the reconstructed document. A foundation for\n  collaborative editing later.\n- **Schema separated from presentation.** Collection definitions are\n  server-safe data; admin UI lives in a parallel `defineAdmin()` config \n  (think Django models vs ModelAdmin, applied to headless content).\n\nFor the longer story, see [docs/02-why-byline/01-mission.md](docs/02-why-byline/01-mission.md) and\n[docs/03-architecture/index.md](docs/03-architecture/index.md).\n\n## Documentation\n\nThe docs live under [`docs/`](docs/) as a numbered, folder-per-section tree —\nitself a Byline-importable markdown repository. Each section has an `index.md`\noverview; the highlights below link straight to the per-topic references.\n\n### 1. [Getting Started](docs/01-getting-started/index.md)\n\n- **[Experimental CLI](docs/01-getting-started/01-experimental-cli.md)** — add\n  Byline to an existing TanStack Start app with `byline init` / `setup`.\n- **[Development environment](docs/01-getting-started/02-development-environment.md)**\n  — clone this repo, bring up Postgres, seed, and run the example app.\n\n### 2. [Why Byline](docs/02-why-byline/index.md)\n\n- **[Mission \u0026 Vision](docs/02-why-byline/01-mission.md)** — why Byline exists,\n  the three pillars, building in the open, and a note on how we use AI in\n  development.\n- **[Content in the Time of AI](docs/02-why-byline/02-content-in-the-time-of-ai.md)**\n  — why structured content management matters more, not less, alongside\n  generative AI.\n\n### 3. [Architecture](docs/03-architecture/index.md)\n\n- **[Document Storage](docs/03-architecture/01-document-storage.md)** — universal\n  storage (EAV-per-type), the seven typed `store_*` tables, flatten/reconstruct,\n  immutable versioning, and indicative benchmark numbers.\n- **[Core Composition](docs/03-architecture/02-core-composition.md)** —\n  forward-looking roadmap for `createCommand`, module registries, a command tree\n  on `BylineCore`, per-realm request-context builders, and `loadConfig()`.\n- **[Transactions](docs/03-architecture/03-transactions.md)** — the transaction\n  model spanning storage writes, hooks, and uploads.\n\n### 4. [Collections](docs/04-collections/index.md)\n\nCollection schema and admin (columns, layout, preview, custom list views) plus\nschema versioning.\n\n- **[Fields](docs/04-collections/01-fields.md)** — field schemas, admin and field helpers.\n- **[Relationships](docs/04-collections/02-relationships.md)** — cross-collection\n  relations, populate, the relation envelope, recursion safety via\n  `ReadContext`, and `hasMany` as a future phase.\n- **[Document Trees](docs/04-collections/03-document-trees.md)** — hierarchical\n  documents, tree mode, and auto-placement.\n- **[Document Paths](docs/04-collections/04-document-paths.md)** — the `path`\n  system attribute (stored in a dedicated `byline_document_paths` table keyed by\n  `(document_id, locale)`), `useAsPath`, the slugifier, and the path widget.\n- **[File \u0026 Media Uploads](docs/04-collections/05-file-media-uploads.md)** —\n  field-level uploads, the two-round-trip flow, `beforeStore`/`afterStore`\n  hooks, and variant persistence.\n- **[Rich Text](docs/04-collections/06-rich-text.md)** — pluggable richtext\n  editor adapter, the current Lexical implementation, and per-field overrides.\n- **[Collection Versioning](docs/04-collections/07-collection-versioning.md)** —\n  schema versioning: Phase 1 (data model + fingerprinting) shipped; later phases\n  deferred.\n\n### 5. [Reading \u0026 Delivery](docs/05-reading-and-delivery/index.md)\n\n- **[Client SDK](docs/05-reading-and-delivery/01-client-sdk.md)** — `@byline/client`\n  as an in-process, server-side SDK: read DSL, write surface, populate, status\n  modes, and what it deliberately is *not*.\n- **[Routing \u0026 API](docs/05-reading-and-delivery/02-routing-and-api.md)** — the\n  internal TanStack-server-fn transport phase, today's server-fn surface, and\n  what triggers a stable HTTP boundary.\n- **[Transports](docs/05-reading-and-delivery/03-transports.md)** — layering\n  framework-agnostic logic under host-specific bindings.\n- **[Markdown Export](docs/05-reading-and-delivery/04-markdown-export.md)** —\n  one-way Lexical-to-markdown rendering, the `.md` URL surface, and `llms.txt`\n  for agent consumers.\n- **[MCP Server](docs/05-reading-and-delivery/05-mcp-server.md)** — exposing\n  Byline content to AI agents over the Model Context Protocol.\n- **[Caching](docs/05-reading-and-delivery/06-caching.md)** — L1/L2 cache layers,\n  the reference `publicCacheMiddleware`, cookie-aware CDN bypass for editors,\n  invalidation strategies, and clustering trade-offs.\n\n### 6. [Auth \u0026 Security](docs/06-auth-and-security/index.md)\n\n- **[Authentication \u0026 Authorization](docs/06-auth-and-security/01-authn-authz.md)**\n  — two auth realms, abilities and roles, the `AbilityRegistry`, service-layer\n  enforcement, and the `beforeRead` hook with worked row-scoping recipes.\n- **[Auditability](docs/06-auth-and-security/02-auditability.md)** — the\n  per-version acting-user trail, the document-level audit log, and the history\n  and activity views built on top of them.\n\n### 7. [Internationalization](docs/07-internationalization/index.md)\n\n- **[Host i18n](docs/07-internationalization/01-host-i18n.md)** — per-request\n  locale resolution and the isomorphic URL rewrite.\n- **[Admin Translations](docs/07-internationalization/02-admin-translations.md)**\n  — `@byline/i18n`, the `byline-admin` bundle, and the extension surface.\n- **[Content Locales](docs/07-internationalization/03-content-locales.md)** —\n  translating content independently of the interface.\n- **[Administering Locales](docs/07-internationalization/04-administering-locales.md)**\n  — configuring and managing locales.\n\n### 8. [Admin UI](docs/08-admin-ui/index.md)\n\n- **[UI Kit](docs/08-admin-ui/01-ui-kit.md)** — `@byline/ui` as a single\n  brand-coherent UI surface: the foundational kit synced from `@infonomic/uikit`,\n  the byline-prefixed cascade-layer system, the `pnpm sync:uikit` workflow, and\n  the `./react/{admin,fields,forms,services}` subpath exports.\n- **[Client-config Registration](docs/08-admin-ui/02-client-config-registration.md)**\n  — how the admin/editor config is registered on the client and code-split away\n  from public routes.\n\n### 9. [Testing](docs/09-testing.md)\n\nUnit and integration suites, the `byline_test` database, and isolation strategy.\n\n## Deployment Scenarios (Current and Future)\n\nByline is designed to support a spectrum of deployment shapes, from a single\nall-in-one host today to fully split admin / API / front-end topologies in the\nfuture. The four diagrams below sketch the progression.\n\n### 1. Integrated all-in-one host (current)\n\nA single host runs the admin dashboard and the front-end application together.\nThe Client SDK runs in-process; the host talks directly to Postgres.\n\n\u003cimg width=\"900\" alt=\"Byline CMS deployment scenario 1: integrated all-in-one host with admin, front-end and Client SDK co-located, connected to Postgres\" src=\"apps/webapp/public/byline-deployment-1-integrated.svg\" /\u003e\n\n### 2. Integrated host with an exposed HTTP API\n\nThe same single host now also exposes a public HTTP API that maps 1:1 to the\nClient SDK. The front-end keeps using the SDK in-process; external clients\nreach Byline through the HTTP API.\n\n\u003cimg width=\"900\" alt=\"Byline CMS deployment scenario 2: integrated host with admin, front-end and an exposed HTTP API mapping 1:1 to the Client SDK\" src=\"apps/webapp/public/byline-deployment-2-integrated-with-api.svg\" /\u003e\n\n### 3. Admin + HTTP API host with a separate front-end host\n\nTwo hosts. The Byline host carries the admin dashboard and exposes the HTTP\nAPI; the front-end is deployed independently and consumes that API over the\nnetwork.\n\n\u003cimg width=\"900\" alt=\"Byline CMS deployment scenario 3: Byline admin and HTTP API on one host, with a separate front-end host consuming the API over the network\" src=\"apps/webapp/public/byline-deployment-3-split-frontend.svg\" /\u003e\n\n### 4. Three dedicated hosts\n\nA dedicated HTTP API server, a dedicated admin host (no exposed HTTP), and a\ndedicated front-end host. The front-end consumes the API host over the\nnetwork; the admin and API hosts share the database.\n\n\u003cimg width=\"900\" alt=\"Byline CMS deployment scenario 4: three dedicated hosts — admin, HTTP API, and front-end — with admin and API sharing a Postgres database\" src=\"apps/webapp/public/byline-deployment-4-three-hosts.svg\" /\u003e\n\n\n\n\n## Quick start - Experimental CLI\n\nNote: We have an experimental CLI that will attempt to install Byline into an existing TanStack Start application. This has only been tested against up-to-date TanStack Start sites created with the Nitro (agnostic adapter). You can install TanStack Start with:\n\n```sh\nnpx @tanstack/cli@latest create\n\n#or\n\npnpm dlx @tanstack/cli@latest create\n```\nThen be sure to select the Nitro (agnostic) adapter.\n```\n◆  Select deployment adapter:\n│  ○ None\n│  ○ Cloudflare\n│  ○ Netlify\n│  ● Nitro (agnostic)\n│  ○ Railway\n└\n```\nOnce your TanStack Start application is ready you can initialize a Byline installation with:\n\n```sh\nnpx @byline/cli@latest init\n\n#or\n\npnpm dlx @byline/cli@latest init\n```\nNOTE: If you use `pnpm` - installing dependencies may bail out asking you to `pnpm approve-builds`\nYou can stop the `cli@latest init` - approve builds, and then re-run `pnpm dlx @byline/cli@latest init` and\nit will pick up where it left off. You may need to do this more than once.\nAt a minimum - for `pnpm \u003e= 11` - you'll need a `pnpm-workspace.yaml` file in the root of your project that looks something like this:\n\n```\nminimumReleaseAge: 1440\nallowBuilds:\n  \"@google/genai\": true\n  \"@parcel/watcher\": true\n  protobufjs: true\n  sharp: true\n\n```\n\n\nIf there are any issues, you can follow the example application in this repo under `apps/webapp`.\n\nNOTE: For AI-assisted editing, you'll need to add your API keys as shown in `apps/webapp/.env.example`\n\nIMPORTANT: The core Byline routes will be placed under a pathless route at `routes/_byline`, with its own route.tsx template. To prevent your front-end TanStack Start application's styling from 'leaking' into the Byline dashboard, you'll need to create or move your top-most layout route into its own pathless layout route - for example, under `routes/_font-end` or `routes/_public` - with any styling, headers, footers etc., that might have been in __root.tsx - moved into the route.tsx layout file inside your front-end pathless layout route.\n\nSee the TanStack Router docs for [File-Based Routing](https://tanstack.com/router/latest/docs/routing/file-based-routing) and [Virtual File Routes](https://tanstack.com/router/latest/docs/routing/virtual-file-routes) for more information.\n\nNOTE: If you have manually configured Byline by copying code from the example application here (byline directories, .env, start, server, __root.tsx, and vite.config.ts settings), and only want to provision the database and seed the super-admin and example docs in the new application, use `byline setup` instead of `byline init`:\n\n```sh\nnpx @byline/cli@latest setup\n\n# or\n\npnpm dlx @byline/cli@latest setup\n```\n\n`setup` runs only the database-provisioning and seed phases (`db` → `db-init` → `seed-admin` → `seed-docs`) — it does not touch project files. Useful flag examples:\n\n```sh\n# Provision the DB and seed both the super-admin and example docs (default)\nbyline setup\n\n# Provision the DB and seed the super-admin only\nbyline setup --no-seed-docs\n\n# Provision the DB and seed example docs only\nbyline setup --no-seed-admin\n\n# Provision the DB without running either seed\nbyline setup --no-seed-admin --no-seed-docs\n\n# Destructive: drop and recreate the database (requires both flags)\nbyline setup --reset --i-mean-it\n\n# Re-run every phase even if recorded as complete (non-destructive on its own —\n# migrations re-apply as no-ops, seeds are idempotent)\nbyline setup --force\n\n# Full nuke-and-pave: drop and recreate the database, then re-run every phase\nbyline setup --force --reset --i-mean-it\n```\n\nBefore running any phase, `setup` performs a quick pre-flight: it bails if the core `@byline/*` packages aren't installed in your app's `package.json`, bails if `.env` is missing, and warns-and-confirms if `.env` is present but missing keys Byline expects (some keys may legitimately be supplied via shell env). For new TanStack Start apps that need the full scaffold, use `byline init` instead.\n\n## Quick start - Development environment and example application (this repo)\n\n```sh\ngit clone git@github.com:Byline-CMS/bylinecms.dev.git\ncd bylinecms.dev\npnpm install\npnpm build\n```\n\nBring up Postgres (Docker, default password `test`):\n\n```sh\ncd postgres \u0026\u0026 mkdir data\n./postgres.sh up -d\n```\n\nInitialise the database, run migrations, and seed:\n\n```sh\ncd packages/db-postgres \u0026\u0026 cp .env.example .env\ncd src/database \u0026\u0026 ./db_init.sh \u0026\u0026 cd ../..\npnpm drizzle:migrate\n\n# .env configuration\ncd ../../apps/webapp \u0026\u0026 cp .env.local.example .env.local\n\n# generate JWT session key\nopenssl rand -base64 48\n# paste the above output into your .env.local file for\n# BYLINE_JWT_SECRET\n\n# Set the seed superadmin username email address and password\n# BYLINE_SUPERADMIN_EMAIL=admin@byline.local\n# BYLINE_SUPERADMIN_PASSWORD=change-me\n\npnpm tsx --env-file=.env.local byline/seed.ts\n```\n\nThen from the project root:\n\n```sh\npnpm dev\n```\n\nOpen http://localhost:5173/.\n\nFull notes — including the foot-gun protection on `db_init`, alternate\ndatabase names, and what the seed does — are in\n[docs/01-getting-started/02-development-environment.md](docs/01-getting-started/02-development-environment.md).\n\n## FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e1. Who are you?\u003c/summary\u003e\nWe’re pretty much nobody — at least not within the usual spheres of influence. We're an agency based in Southeast Asia, and we're fairly certain you've never heard of us. That said, we have a lot of experience building content solutions for clients — and we’re tired of fighting frameworks for core features our clients need and expect.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e2. Will this work?\u003c/summary\u003e\nWe hope so. Core is stable but there certainly still work to do.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e3. What governance structures are you considering?\u003c/summary\u003e\nWe really like the governance structure of [Penpot](https://community.penpot.app/t/penpots-upcoming-business-model-for-2025/7328). We're committed to 100% open-source software, with no \"open core\" or \"freemium\" gotchas.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e4. Would you accept sponsorship?\u003c/summary\u003e\nYes!\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e5. Would you accept venture or seed-round investment?\u003c/summary\u003e\nWe’re not certain yet, and likely not at this early stage. Our priority is to figure out key aspects of the project first. What we feel strongly about, however, is that community contributions should remain accessible — not locked behind an enterprise or paywalled solution. Ultimately, our governance structure and commitment to being community‑driven will guide any financial decisions we make.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e6. What's here now?\u003c/summary\u003e\nThe storage, versioning, workflow, auth, client SDK, and admin UI are all in place. We're shipping under the 3.x line but treating it as a release candidate: APIs are stable and the core architecture is settled, with several capabilities (collection-versioning history, `hasMany` relations, list-view materialisation under load) deferred to fill in across the 3.x line.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e7. Why the Mozilla Public License (MPL-2.0) Version 2.0?\u003c/summary\u003e\n\nWe chose the MPL as we feel this represents the best balance between community-driven open source software, and allowing commercial value-based services to flourish.\n\nThe Mozilla Public License 2.0 (MPL-2.0) is often described as a “file-level copyleft” license. That means it sits somewhere between very permissive licenses (like MIT or BSD) and strong copyleft licenses (like GPL). In simple terms: if someone modifies MPL-licensed source files, those modified files must remain open and distributed under the MPL. However, they can combine those files with their own proprietary code in the same larger project, as long as they keep the MPL files separate and respect the license terms.\n\nThis creates a clear boundary. Improvements to the original open-source codebase stay open and benefit the community. At the same time, companies can build additional features, integrations, services, or proprietary modules around it without being required to open-source their entire product. The obligation applies only to the specific MPL-licensed files that are modified or redistributed — not to the entire application.\n\nPractically speaking, if someone uses MPL-licensed software in a commercial product, they can sell that product, host it as a service, or build paid offerings around it. If they modify the original MPL files and distribute those modifications, they must make those specific changes available under the MPL. If they simply link to or use the software without modifying those files, there is no requirement to open their own independent code.\n\nWe feel the MPL will help to encourage collaboration and shared maintenance of the core platform, while still supporting sustainable commercial ecosystems — which is why many teams see MPL-2.0 as a pragmatic middle path between fully permissive and strongly reciprocal open-source licenses.\n\u003c/details\u003e\n\n## License\n\nMozilla Public License 2.0. See [LICENSE](LICENSE) and [COPYRIGHT](COPYRIGHT).\n\nCopyright © 2026 Infonomic Company Limited\n\n### Major Contributors\n\n- Anthony Bouch — https://www.linkedin.com/in/anthonybouch/ — anthony@infonomic.io\n- David Lipsky — https://www.linkedin.com/in/david-lipsky-4391862a8/ — david@infonomic.io\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyline-cms%2Fbylinecms.dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyline-cms%2Fbylinecms.dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyline-cms%2Fbylinecms.dev/lists"}