Core and ext · Docs

Two repositories and one runtime: what belongs in core, what belongs in ext and how the folders are laid out.

Two repositories, one runtime

Nimbly splits every project into two separate git repositories that live nested on disk:

Repository	What it is	Who owns it
core	The Nimbly framework - routing, template engine, shortcodes, admin, API	Nimbly (never modified per project)
ext	Your application - routes, templates, data, custom shortcodes	You (every project has its own ext repo)

On disk they combine into one directory tree:

my-project/          ← core repo root
  core/              # Framework internals
  ext/               ← ext repo root (nested inside core)
  css/               # CSS source (shared build)
  js/                # JS source (shared build)

This means git status at the project root reflects core changes; git status inside ext/ reflects application changes. They are independent repos with independent histories, branches, and remotes.

They are also licensed separately: core is open source under the ISC license, while every ext repo is proprietary - copyright Nimbly Web Systems, all rights reserved - and carries its own ext/LICENSE.txt.

Deciding core vs. ext

The "never modify core" rule is about not bending core's existing framework code to fit one app. It is not a rule about where new framework-level features belong. Ask: would every Nimbly app need this, not just this project?

Yes → core. Built-in admin screens, generic resource CRUD, auth/roles/permissions, shortcodes any project could use. If getting basic functionality working in a new project would mean copy-pasting the same files into every ext repo, that's a sign the feature is stranded in the wrong place.
No → ext. This project's own resources, routes, business logic, branding, and config - anything that only makes sense for this specific application.

Concrete example of getting it wrong: the role editor (/nb-admin/roles/(id) and /nb-admin/roles/add) was originally built entirely in ext/uri/nb-admin/roles/, even though every other admin resource page (users, media, jobs, ...) is served generically from core/modules/admin/uri/nb-admin/(resource)/... with no per-project override at all. Roles/permissions are core to Nimbly's own permission system, not app data - so that route belonged beside debug/, media/, profile/ etc. under core/modules/admin/uri/nb-admin/, not in ext. Leaving it in ext meant every new project would have to hand-copy those files just to manage roles.

Directory layout

core/          # Framework - never modify
  lib/         # Core libraries and shortcode implementations
  modules/     # Core modules (admin, forms, api, install, user)
  tpl/         # Core templates (html wrapper, etc.)
  uri/         # Core routes
ext/           # Your application - all custom work goes here
  data/        # Resources (.meta + JSON records)
  lib/         # Custom libraries and shortcode implementations
  modules/     # Custom modules
  tpl/         # Reusable templates
  uri/         # Route templates
  static/      # Built assets (output of npm build)
css/           # CSS source
js/            # JS source (JSX/Alpine)

Rule: Never modify core/. All customization lives in ext/.

Rule: All text in core/ must be in English. Use [#text Key#] for every user-facing string so projects can supply translations via ext/data/.i18n/text.<lang>.po. Never hard-code Dutch or any other language in core templates.