Developer documentation
Developer documentation
Kwisple is one platform for a client's whole digital presence: website, brand kit, social content, statistics, forms and requests, managed by an agency for its clients. Websites are custom code in their own repository; the platform is the CMS, the API, the hosting and the dashboard around them. This documentation is for the developers who build those websites and their custom modules, and for the people who work on the platform itself.
Start here
What Kwisple is, for developersThe platform model, what the platform provides versus what lives in your site repository, the three site modes, and how "AI assists, never leads" affects your work.Quick start: five minutes to live contentCreate a site from a starter, log in from the terminal, link it to a client's website, run it locally with live content, add a block, push the model and connect the repository.ConceptsShort definitions of everything you meet when building on Kwisple, with links to the detailed pages.
Your site repository
Structure and configuration
- Project structure (Next.js)Every folder and file of the Next.js starter explained, what it does and when you touch it, plus how a grown production site (RANSON.N) extends it.
- Project structure (Astro)Every folder and file of the Astro starter explained, the @kwisple/sdk/astro integration and its options, and where Astro differs from the Next.js starter.
- Environment variables and tokensEvery KWISPLE_* variable a site reads, where it comes from, build-time versus runtime, per environment, and how site tokens and their scopes work.
Rendering
- Rendering contentTurn a request path into a typed entry and render it with views, the page builder, rich text, images, links, navigation and globals, with redirects and 404s handled for you, in Next.js and Astro.
- Live preview and revalidationHow the dashboard previews drafts on your site, how a publish reaches your cache through the signed webhook, what "Cache legen" does, and when a site rebuilds instead.
- SEO, performance and security headersThe SDK's metadata, JSON-LD, sitemap and robots helpers, the Lighthouse guard, image and font defaults, and the security headers and frame-ancestors policy a production site needs.
Going live
- Hosting and deploysConnect a site repository in the dashboard, choose between Cloudflare, your own host with a deploy hook or the platform's own server, and control what happens on publish, on redeploy and for pull-request previews.
- StagingGive a custom-code site a staging environment with its own content, address and password, deploy the staging branch behind the SDK's gate, and move code to production with "Naar productie".
- Domains and DNSAdd a client's domain to a website, choose where the site runs so the dashboard shows the right records, verify them with "Controleer records", pick the primary domain and handle www and Cloudflare's proxy.
Content model
Schema as codeHow a site's content model is declared in cms.config.ts with defineSchema, defineSection, defineEntryType, defineGlobalSet and defineForm, and how it becomes the editor in the dashboard.Fields referenceEvery field helper in f, with its options, the stored value, the value the SDK returns, how the editor shows it and what the engine validates on publish.Blocks and relationsMatrix blocks (the page builder), relations to entries and assets, and link fields: how to declare them, what the SDK returns and how the dashboard presents them.Localisation and URIsLocales per site, translatable versus shared fields, URI formats and slugs, structures, automatic redirects when a URI changes, and how the delivery API answers per locale.Workflow: dev, push and changesHow a change to cms.config.ts travels from your editor to the live content model with kwisple dev, kwisple push and CI, and why a push never deletes content.Site kits: seed and exportStarting content as one JSON file, written into a site with kwisple seed and made from a finished site with kwisple export.Coming from Craft CMSA map from Craft CMS 5 concepts and plugins to Kwisple, a migration approach based on the RANSON.N rebuild, and what has no counterpart.
Content and data
Delivery APIThe HTTP API a custom-code site reads its content, brand, privacy settings and forms through, with every endpoint, header, error code and rate limit.SDK clientcreateClient and every method of the typed KwispleClient, plus the Next.js and Astro helpers that wrap it.Querying entriesEvery option of EntriesQuery: sections and types, field filters and their operators, sorting, pagination, picking fields, locales, trees and related entries, with examples for the common tasks.CachingWhere delivery answers are cached, which tags they carry, what publishing purges, the signed revalidation webhook to your site, Cache legen, scheduled purges and patterns for Next.js and Astro.Forms, bookings and confirmationsDeclare forms with defineForm, submit them from your site's server, take bookings with slots, send confirmation mails, and follow submissions up in the dashboard.Statistics and consentThe platform's cookieless statistics script, what it sends and how visitors are counted, the generated cookie banner and consent log, and how AI-agent visits are reported from your server.Brand kit and privacy dataWhat client.brand() returns (colours and their pairings, fonts, logos per role, brand elements, voice) and how to use it in a site, plus client.privacy() for the privacy and cookie pages and the client's business details in JSON-LD.
Apps: custom modules per client
Apps overviewCustom work for one client, built in that client's site repository and shown in their dashboard as an app with the dashboard's frame, rights and data around it.Declaring an appThe defineApp options, who gets to open an app and with which level, and how the app appears in the client's dashboard after a push.Building the pageThe app's page in your site, connectApp from @kwisple/sdk/app, the framing requirements and UI advice, with the RANSON.N components as examples.Server side: sessions, rights and platform dataVerifying the app session on your server with appSessionFrom, acting on the platform as the person with appPlatform, and the apps API on the dashboard behind it.Example: a booking deskRANSON.N's Boekingen app end to end, from the appointment form on the website to confirming, declining or proposing another moment in the dashboard.Example: a generator toolThe RANSON.N Golfgenerator, a brand tool without platform data ported from a Craft project, and the general recipe for any client-specific tool.Security modelHow the app session is signed, delivered and renewed, what your site must verify on every request, what never to do, and framing rules including white-label dashboard hosts.
Integrations
Outgoing webhooksSigned HTTP notifications per client for form submissions, leads, requests and publications, with the payloads, signature check, retries and delivery log.MCP connectors and OAuthConnect Claude or any MCP client to the platform with a personal token or OAuth 2.1, what every MCP tool may do, and why an AI connection only ever proposes.
CLI
CLI referenceEvery kwisple command and flag, how login and linking work, where credentials are stored, exit codes and the environment variables the CLI reads.CI and automationA CI token with read and schema scopes, the GitHub Actions workflow that checks the content model on pull requests and pushes it on main, and how that relates to deploys and publishing.
The platform repository
Getting around
- Monorepo overviewWhat lives where in the platform repository, which app or package depends on which, what runs on which port, and how a request travels through the system.
- Local setupPrerequisites, infrastructure containers, environment variables, database setup and the commands that run the dashboard, web app, worker, agent and starters on your machine.
- ConventionsThe rules the platform code follows, each with the reason behind it and a short example from the codebase.
How it works
- Tenancy and permissionsThe three-level tenancy model, the forWorkspace query guard, sessions and workspace resolution, permission keys, the access policy, "Bekijk als klant", the inbox and how agents get exactly a person's rights.
- The content engineHow @kwisple/cms and @kwisple/content store, validate, publish and serve content, what happens after a publish, how apps/web delivers it and where assets live.
- Jobs and the workerBackground work on pg-boss through @kwisple/jobs - every job, the enqueue options, concurrency, schedules, the worker process, inline jobs in development and how to add a job.
- Languages and design systemHow the dashboard speaks Dutch, French and English (catalogues, translators, formatter, the i18n check) and how its screens are built from the design tokens and primitives.
Working on it
- Adding things: recipesStep-by-step recipes with file paths for the changes you make most often in the platform repository, from a dashboard page to a delivery API endpoint.
- Testing and checksEvery check the platform repository has - typecheck, lint, the i18n and action guards, unit and database tests per package, end-to-end tests, the backup drill, Lighthouse, the docs content tests and the release dry run - and what CI runs.
- Deploying the platformThe production shape of the platform - one VM with Docker Compose, the multi-target Dockerfile, env files per service, Caddy, the go-live scripts, migrations, rollback, backups, health checks and how it scales.
Help
TroubleshootingSymptom, cause and fix for the problems developers meet most, grouped by area, with the exact messages the CLI, the SDK and the dashboard print.GlossaryThe terms of the platform in alphabetical order, with the Dutch label the dashboard uses where it differs and a link to the page that explains each one.