JavaScript Implementation
The JavaScript layer is Superloom's reference implementation: Node.js 24+, Express on Docker and AWS Lambda for the server, GitHub Packages for module distribution, and the built-in Node.js test runner throughout. Every document in this layer is complete on its own; a JavaScript developer works from here without needing the principles layer.
These documents dictate the JavaScript way. The reasoning behind each rule lives in principles/; each document below implements one or more principles documents, per the mapping table.
Reading Path
For a developer new to the framework, in order:
- Project Structure - the directory layout and repository conventions
- Code Formatting - spacing, banners, comments, naming, JSDoc
- Module Structure - loaders, companions, patterns, and every archetype skeleton
- Module Classes - the class taxonomy and where every module belongs
- Error Handling - envelopes, catalogs, throw versus return in JavaScript
- Testing Strategy and Unit Test Authoring
- Client Architecture - the RNW/Expo stack, project layout, and bundler-agnostic rule (entry point to the
client/section)
Document Map
| Document | Implements |
|---|---|
project-structure.md | Engineering Philosophy |
code-formatting.md | Code Readability |
module-structure.md | Module Design, File Archetypes |
factory-vs-singleton.md | Module Design |
module-classes.md | Module Design |
dependencies.md | Module Design |
error-handling.md | Error Handling |
validation.md | Validation |
testing-strategy.md, unit-test-authoring.md, module-testing.md, integration-testing.md | Testing |
module-docs.md, module-docs-complex.md, module-thoughts-file.md | Module Design, Documentation Authoring |
publishing.md, versioning/ | Versioning and Releases |
dto-philosophy.md, server/ | Server Architecture |
client/ | Client-side architecture: stack, loader, theming, fonts, components, super-app shapes, module taxonomy |
catalog-core.md, catalog-server.md, catalog-client.md | The published module catalog per tier |
pitfalls-migration.md | Pitfall journal for module migration work |
Module Repositories
| Repository role | Contents |
|---|---|
| JS implementation repository | All helper modules: src/helper-modules-core/, src/helper-modules-server/, src/helper-modules-client/, and the publish pipeline |
| JS reference application | The working demo application: models, server layers, ops runbook |
Repository names and the full multi-repo layout: org-structure.md.
Naming Forms (Two-Form Rule)
A JavaScript module's name exists in exactly two forms:
| Form | Example | Where it may appear |
|---|---|---|
| Published identity | @superloomdev/js-helper-utils | package.json only (name, dependency targets, repository field) |
| Alias short-name | helper-utils | Everywhere else: documentation prose, titles, code comments, JSDoc, error prefixes, banners, ROBOTS.md |
The bare package name (js-helper-utils) is a directory-layout identifier, acceptable only in URLs that address a real repository path. There is no third form. The alias derivation rule (strip js- and the server/client tier word, keep the rest) lives in code-formatting.md.
This is what keeps the ecosystem forkable: a consumer who renames the scope edits package.json files and nothing else.