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:

1. Project Structure - the directory layout and repository conventions
2. Code Formatting - spacing, banners, comments, naming, JSDoc
3. Module Structure - loaders, companions, patterns, and every archetype skeleton
4. Function Naming - the verb catalog, return shapes, confusable pairs, and banned verbs
5. Module Classes - the class taxonomy and where every module belongs
6. Composition and Adapters - the four tiers in JS, host adapters, the adapter gate
7. Error Handling - envelopes, catalogs, throw versus return in JavaScript
8. Testing Strategy and Unit Test Authoring
9. Server Common - the composition root, loader, and shared runtime foundation
10. Server Interfaces - the Express and Lambda entry points
11. Connection Lifecycle - three lifetimes, two teardown scopes, the deployment rule
12. Client Architecture - the RNW/Expo stack, project layout, and bundler-agnostic rule (entry point to the client/ section)
13. React Native Environment Setup - system prerequisites, local development, Metro bundler
14. Expo Guide - Expo capabilities, adapter pattern, cloud account features
15. React Native Testing - testing conventions for RN and Expo modules

Document Map

Document	Implements
project-structure.md	Engineering Philosophy
code-formatting.md	Code Readability
module-structure.md	Module Design, File Archetypes
function-naming.md	Code Readability
factory-vs-singleton.md	Module Design
module-classes.md	Module Design
composition-and-adapters.md	Composition and Adapters
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/connection-lifecycle.md	Server Architecture
client/	Client-side architecture: stack, loader, theming, fonts, components, super-app shapes, module taxonomy, RN environment setup, Expo guide, RN testing
catalog-core.md, catalog-server.md, catalog-client.md	The published module catalog per tier
conventions-registry.md	Settled micro-conventions lookup table
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.