Developing Nibble

This section is for working on Nibble itself. If you are building a site with Nibble, you want Building a theme instead — you should almost never need to change Nibble to build a site, and if you do, that is worth saying out loud in an issue.

The pages

Page	What it covers
Architecture	how a request becomes a page, the modules, and where code lives
Invariants	the rules the codebase holds to, and the tests that enforce them
Tests and checks	bin/ci and everything it runs
End-to-end tests	the browser suite and the playground
Deployment	Kamal, and what a container does before it serves
Releases	cutting one, and what a site sees
Contributing	sending a change back
Commands	every nibble:* command in one place

Getting set up

git clone https://github.com/mah3uz/nibble.git
cd nibble
bin/setup
bin/dev

bin/setup installs dependencies and prepares the database. bin/dev starts the application, the asset build and server-side rendering together.

Before you push anything:

bin/ci

That is the same suite that guards a release: Ruby and JavaScript style, types, schema, security, both test suites, the asset build and a server-rendering smoke test. It takes well under a minute.

The shape of the thing in one paragraph

Rails 8 serves both the public site and the control panel through Inertia and Vue 3, rendered on the server. SQLite holds the content, the cache and the job queue — one file, no separate services. Content is schema-driven: YAML declares what exists, and entries are rows whose fields are validated against a blueprint. Uploads go to S3 behind a CDN. Deployment is Kamal onto a plain virtual machine.

Read Architecture for the detail, and Invariants for the handful of rules that are not negotiable.