adonisjs/core
github.com/adonisjs/core ↗ · 230 files · 683 KB
@adonisjs/core Featured sponsors Fullstack MVC framework for Node.js AdonisJs is a fullstack Web framework with focus on ergonomics and speed .
Overview
@adonisjs/core 7.5.2 is the TypeScript integration layer for AdonisJS, a Node.js framework for web applications and services. It connects application lifecycle management, dependency injection, HTTP handling, validation, encryption, templates, and developer commands through providers and stable package exports. Distinctive features include lazy command loading, configurable scaffolding, generated route and transformer types, and machine-oriented CLI output.
System map
The repository packages the integration surface of AdonisJS rather than implementing every framework subsystem locally. Ignitor creates web, console, and test processes, while providers register the services those processes consume. Package exports separate public modules, service facades, providers, factories, helpers, and commands. Persistent outputs inspected here are generated application files and development artifacts; token persistence is delegated to consumers. Distribution and release are centered on an npm ESM package.
- The package is @adonisjs/core 7.5.2, requires Node >=24.0.0, uses ESM, and publishes build output while excluding built tests and bin files.
- index.ts exports Ignitor, prettyPrintError, inject, configProvider, indexEntities, and stubsRoot, and aggregates errors from the application, HTTP, encryption, Ace, and environment packages.
- Public subpath exports expose commands, factories, services, providers, helpers, lifecycle entrypoints, drivers, and framework modules through compiled build paths.
- Application and HTTP primitives are re-exported from @adonisjs/application and @adonisjs/http-server; the HTTP wrapper also loads bodyparser augmentation and exports the local RequestValidator.
- Ignitor creates Application with an environment and optional importer, sets the shared app service, runs tap callbacks, and constructs HttpServerProcess, AceProcess, or TestRunnerProcess.
- AppServiceProvider.register wires application, Ace, dumper, logger, config, events, encryption, test utilities, server, router, and bodyparser bindings; its boot hook assigns the emitter to BaseEvent.
- The framework Server singleton receives application, default Encryption, emitter, logger, and app.http configuration; Router resolves to that server's router.
- The inspected storage boundaries include generated route declarations and JSON, scaffold destinations, and REPL history under the user's home directory.
- npm run compile cleans build, runs tsdown and declaration-only tsc; postcompile copies stub templates and indexes commands. The test script invokes Japa through @poppinss/ts-exec.
- The package binary adonis-kit constructs an Ace kernel containing IndexCommand, which generates a lazy command index from a directory relative to cwd.
- Release CI waits for checks, uses the npm-publish environment with contents and OIDC write permissions, installs with npm ci --ignore-scripts, audits signatures, verifies generated command artifacts, and invokes release-it.
Feature catalog
The developer-facing product includes application startup APIs, scaffolding, package configuration, inspection commands, development serving, production builds, and test orchestration. HTTP integrations add VineJS request validation and Edge rendering to dependency-provided request and routing APIs. Security utilities include configurable hash and encryption drivers and verification-token helpers. Generated declarations connect server routes and transformers to application type checking. This catalog reflects the inspected public surfaces, not exhaustive dependency behavior.
- serve supports watch, HMR, polling, and terminal clearing; it rejects simultaneous watch and HMR and delegates startup to assembler.DevServer.
- build delegates production compilation to assembler.Bundler with RC hooks and meta files, optional tsconfig and package manager, and an ignore-ts-errors switch.
- codegen refreshes generated indexes and route declarations through assembler.CodeGen and warms the app in the web environment without starting an HTTP listener.
- test exposes suite, file, tag, group, title, reporter, timeout, retry, failed-test, watch, and polling controls, then passes these to assembler.TestRunner.
- add installs multiple packages before configuring them sequentially, recognizes vinejs and edge shorthand names, and reports partial configuration failures; configure supports built-in VineJS, Edge, and health_checks setup plus package-exported hooks.
- list:routes offers keyword and middleware filters, ANSI list/table, JSON, and JSONL output; AI-agent mode defaults to JSONL unless JSON or table is explicitly requested. inspect:rcfile prints resolved RC settings with module entries stringified.
- generate:key creates a 32-character APP_KEY, normally writes outside production, honors force, and lets show override writing; env:add prompts for values and adds a normalized variable plus its validation schema.
- make:controller supports custom actions, resource/API variants, singular naming, force, and contents-from. make:validator, make:view, and make:transformer also generate entities through configurable stubs.
- make:command, make:service, make:event, and make:exception each pass parsed flags and an application-generated entity into Codemods.makeUsingStub, with overwrite and replacement-content options.
- make:listener can create its associated event first; make:middleware generates and registers middleware in server/router/named stacks; make:preload and make:provider optionally register environment-scoped RC entries.
- make:test selects a configured suite and destination directory; eject copies package scaffolding templates into the application for customization.
- repl boots the application and stays alive until REPL exit; its provider adds importDefault, importAll, make, service-loading helpers, and persistent history.
Data flow
Application-root URLs and RC configuration feed lifecycle creation and lazy container bindings. Incoming HTTP traffic crosses from a Node server into the dependency-provided framework handler, while local validation adapters assemble request data for VineJS. CLI inputs become command state, generated entities, AST transformations, or assembler operations. Development routing data is written to disk and announced to the parent process; standalone codegen passes equivalent serialized routes in memory. Verification tokens separate public secrets from hashes intended for consumer-owned persistence.
- Ignitor passes appRoot, environment, and importer into Application, then publishes the instance through setApp before running tap callbacks.
- Encryption configuration flows from app.config.get('encryption') through configProvider.resolve into EncryptionManager; the default Encryption class binding calls manager.use().
- HTTP requests and responses enter server.handle through a bound Node HTTP handler; the framework server retains the Node server through setNodeServer.
- RequestValidator spreads request.all() first, then assigns params, headers, and cookies from their request APIs, making these reserved fields override same-named body properties.
- Validation options receive request-specific defaults only when caller overrides are missing; options.data replaces automatic request assembly before validate or tryValidate receives the data.
- Multipart schema values are checked for the isMultipartFile marker; configured limits fill missing file limits, file.validate runs, and file.errors are translated into VineJS reports.
- Controller CLI input becomes an entity through app.generators.createEntity; the selected stub calculates class/file names and exports its destination through app.httpControllersPath before stub generation writes it.
- Committed router state feeds router.generateTypes(2), which is written as ScannedRoutes plus RoutesList augmentation; development output also serializes router.toJSON and notifies the parent of routesFileLocation.
- Standalone codegen JSON-round-trips router.toJSON to discard closure handlers and unserializable properties, then returns that route shape to the assembler callback.
- Edge clientRoutes exports only named routes and selects domain, methods, pattern, tokens, and name; routesJSON turns this selected structure into JSON.
- VerificationToken.seed returns a Secret and SHA-256 hash; transient tokens add userId and expiration, computeValue encodes identifier and secret, and verify compares a recomputed hash without performing persistence itself.
Behavior traces
The principal flows were followed across entrypoints, providers, adapters, and output code. HTTP startup establishes lifecycle and dependency ordering before listening. Request validation moves from a provider-installed request macro to context-derived data and a compiled VineJS validator. Controller generation moves from Ace dispatch through command lifecycle and stub generation to a destination file. Additional traces cover generated route persistence, codegen ordering, package setup, shutdown, and test startup.
- HTTP startup: Ignitor.httpServer() → HttpServerProcess.start() → Ignitor.createApp('web') → app.init() → app.boot() → app.start(callback) → container.make('server') → server.boot().
- HTTP listen/readiness: start callback → createHTTPServer(server.handle.bind(server)) → server.setNodeServer → #listen → app.notify → logger.info → emitter.emit('http:server_ready') → #monitorAppAndServer.
- HTTP shutdown: app.terminating callback → #close → nodeHttpServer.close; a post-start server error instead sets process.exitCode=1, logs fatal, and calls app.terminate.
- Ace dispatch: AceProcess.handle(argv) → createApp('console') → app.init → createAceKernel(app, commandName) → bindValue('ace') → loading hook optionally boots/starts the app → configure callback → kernel.handle → conditional termination.
- Controller scaffolding: BaseCommand.exec hydrates and invokes prepare/run through the container; MakeController.prepare selects main/actions/resource/API stub; run creates Codemods, sets force, builds entity state, and calls makeUsingStub.
- Scaffold persistence: makeUsingStub → app.stubs.create → stubs.build → optional readFile/replaceWith → stub.generate → relative destination normalization → skipped/succeeded CLI action. The controller stub sets its output path through exports({to: ...}).
- Request validation: VineJSServiceProvider.boot installs HttpRequest.validateUsing → new RequestValidator(request.ctx) → #processValidatorOptions → options.data or #requestData → validator.validate. tryValidateUsing follows the equivalent path with validator.tryValidate.
- Development route persistence: AppServiceProvider.ready checks !inProduction and router.commited → emitRoutes → emitRouteTypes → mkdir/writeFile routes.d.ts → writeFile routes.json → app.notify; failures are caught and logged.
- Standalone generation: Codegen.run → importAssembler → new CodeGen with RC hooks → codegen.run callback after index output → #warmUpApp → setEnvironment('web')/setMode('warmup') → boot/warmUp → router.commit → emitRouteTypes → JSON route return.
- Package setup: Add.run resolves shorthand npm names → createCodemods → installPackages → sequential kernel.exec('configure') → built-in setup or app.import(package) → packageExports.configure(command) → aggregate success/failure reporting.
- Application test startup: TestRunnerProcess.run → createApp('test') → init → boot → start(configure callback) → user test callback; the method does not itself terminate the application.
Testing signals
Tests and CI were inspected, not executed; no passing result or coverage percentage is asserted. The Japa runner discovers repository specs and enables assertion, type, filesystem, and snapshot plugins. Inspected tests cover lifecycle transitions, actual HTTP interactions, validation, scaffolding, codegen order, file-format preservation, and encryption compatibility. Some tests perform real package installation or bind ports, so execution is not purely isolated computation. The inventory and coverage assessment are bounded rather than exhaustive.
- bin/test.ts processes runner arguments, discovers tests/**/*.spec.ts, installs assert/expectTypeOf/fileSystem/snapshot plugins, and calls run; these definitions were inspected without execution.
- npm test runs lint first and invokes quick:test with NODE_DEBUG=adonisjs:core; quick:test starts bin/test.ts with the TypeScript import hook and --force-exit.
- HTTP lifecycle specs use Supertest against a real started server and assert response content, default port behavior, shutdown, occupied-port rejection, and crash exit status.
- An Ace regression test exercises a staysAlive command calling app.terminate during run and asserts both process.exitCode=1 and terminated application state.
- Validation specs assert required-field error details, successful output and inferred TypeScript type, and tryValidateUsing success/error tuples.
- Controller command tests compare exact generated contents, verify existing files are skipped, cover singular API/action variants, and exercise absolute contents-from input.
- Codegen tests check missing-assembler handling, warmed web state, route declaration output without routes.json, and the requirement to generate controller indexes before providers boot.
- Codemods tests assert CRLF/indentation, minified JSON, BOM preservation, existing-alias immutability, and missing-file errors; installation tests actually request @adonisjs/assembler and assert its node_modules directory.
- Legacy encryption specs assert rejection of tampered ciphertext, MAC, and IV, cross-decryption with the old v6 encrypter in both directions, and compatible 16-byte ASCII-safe IV encoding.
- safeTiming tests cover minimum duration, returned values, slow callbacks, early return, and thrown Error objects; the inspected file does not exercise falsy thrown values. Dumper tests exercise HTML, CSP nonce, ANSI output, and dd exceptions, without adversarial title/link inputs in that file.
- CI definitions were inspected, not executed: checks delegates test, lint, and typecheck jobs; test.yml runs npm test on Linux and Windows with lts/krypton and latest Node, while release verifies built command files.
- c8 configuration lists text/html reporters and excludes tests, build, factories, and .yalc; the inspected npm test and CI test commands do not invoke c8 or specify a coverage threshold.
Risk map
These are source observations and explicitly labeled hypotheses, not confirmed vulnerabilities. Sensitive boundaries include network listeners, package installation and hooks, arbitrary replacement-file reads, generated-file writes, home-directory REPL history, cryptographic compatibility, and diagnostic HTML. Lifecycle and generated-artifact ordering create broad coupling between providers, services, and developer tooling. No exploit, production configuration, dependency implementation, or runtime outcome was verified.
- HTTP startup binds HOST or 0.0.0.0 and PORT or 3333 using Node createServer by default; a caller-supplied server factory is the local hook for HTTPS or other server customization.
- generate:key can write APP_KEY through EnvEditor or print it to logs; --force permits production writes and --show overrides force. This is a sensitive operator command, not an inspected secret file.
- Codemods.makeUsingStub intentionally accepts absolute contents-from paths and reads their UTF-8 contents; generation also supports forced replacement of destination files.
- add crosses a package-installation boundary through assembler CodeTransformer.installPackage and then executes imported package configure hooks with the command object. Shell/process details belong to the assembler dependency and were not established here.
- The REPL provider stores history at homedir()/.adonisjs_v6_repl_history and exposes module import and container construction helpers, making it a privileged local development surface outside the application root.
- Ignitor explicitly assumes one entrypoint creates the application per process; setApp overwrites shared module state and service facades resolve through that shared app's boot hook.
- configProvider.resolve checks only that an object has a type property before calling resolver; it does not locally check type==='provider' or resolver callability.
- Optional-import helpers swallow import errors, and Codemods.#getCodeTransformer also catches all initialization errors; broken packages can therefore reach the same missing-dependency path as unavailable packages.
- Route generation requires committed routes and correctly ordered generated indexes; development emitRoutes catches write failures and continues after logging, while standalone codegen depends on indexes existing before boot.
- Legacy encryption intentionally preserves v6 string-IV and ciphertext formatting, verifies HMAC before decryption, and rejects blind-index operations; edits have a compatibility blast radius documented by cross-version tests.
- Hypothesis requiring targeted verification: diagnostic HTML could be unsafe if callers supply untrusted titles, source metadata, editor templates, or CSP nonces, because these wrapper values are directly interpolated into HTML. The inspected tests use ordinary values and do not establish exploitability. (inferred)
- Hypothesis requiring a regression test: safeTiming may resolve after a callback throws null, false, 0, or an empty string because it rethrows only when caughtError is truthy; inspected error tests throw Error objects. (inferred)
Extension points
Extension is organized around application providers, container bindings, command loaders, macros, configuration factories, and assembler hooks. Types expose open interfaces for application-specific services and registries. Stubs and codemods let packages add generated entities and modify consumer applications. The public export map and compiled command index connect these extension mechanisms to package distribution.
- Ignitor.tap provides application setup callbacks and IgnitorOptions.importer allows custom module resolution during Application construction.
- HttpServerProcess.start accepts a factory receiving the framework request handler and returning a Node HTTP or HTTPS server.
- Ace loads RC command modules through callable or string import loaders and supplements them with FsLoader over app.commandsPath; a known already-registered command can skip application command metadata loading.
- BaseCommand subclasses declare options and lifecycle methods; exec invokes prepare, interact, run, and completed through container.call, enabling dependency injection into command hooks.
- Package configure hooks receive the Configure command, including parsedArgs, parsedFlags, optional package stubsRoot, and a Codemods instance configured for force/verbose behavior.
- Codemods exposes AST extension methods for middleware, policies, RC settings, Vite and Japa plugins, validators, limiters, model mixins, and controller methods through assembler CodeTransformer.
- indexEntities returns an assembler init hook with configurable sources, aliases, globs, skipped segments, enablement, transformer shared props, and manifest exclusions.
- Hash defineConfig accepts direct driver factories or configuration providers; encryption defineConfig accepts concrete configurations or providers, and BaseDriver is exported for custom encryption drivers.
- EventsList, LoggersList, HashersList, EncryptorsList, and ContainerBindings are exported interfaces intended for type augmentation; generated route declarations augment RoutesList.
- Vine and HttpRequest are extended with macros; Edge extends HttpContext through a view getter and BriskRoute through render, while RequestValidator exposes static per-request reporter and message-provider factories.
- Local scaffold customization is supported by eject and app.stubs.build; new public module surfaces also require coordination with package exports and tsdown entry configuration.
- TestUtils extends Macroable, and IgnitorFactory supplies merge, preload, core-provider, and core-configuration hooks for constructing test applications.
Contributor handoff
Work from the pinned source and preserve the boundary between local integration code and dependency-owned implementations. Read lifecycle, provider, and service files together before changing startup or container behavior. Generator changes require reviewing commands, codemods, templates, generated types, and package output configuration as appropriate. Tests and CI were inspected, not executed; this report is a bounded source investigation and supplies no passing-test evidence. Future verification must respect authorization because some repository tests install packages, write fixtures, and open listeners.
- Read package.json, index.ts, Ignitor, and AppServiceProvider first for public exports, application creation, and baseline service registration; these files define the primary integration boundaries.
- Preserve the shared-application initialization order and booted service resolution; services/server.ts and services/encryption.ts use top-level await to resolve bindings through app.booted.
- Follow the npm lockfile and existing scripts: quick:test is the direct Japa entrypoint, lint runs eslint, typecheck runs tsc --noEmit, and npm test adds lint plus debug-enabled runner execution.
- Tests and CI were inspected, not executed in this investigation. Their source describes intended checks and assertions, not observed successful results.
- Use task-specific specs as initial verification candidates when execution is authorized: HTTP/Ace lifecycle specs for process edits, controller command specs for scaffolding, and codegen specs for generated-output ordering.
- Account for test side effects before executing: Codemods installation tests fetch dependencies, HTTP tests bind ports and mutate process environment, and Ace lifecycle tests manipulate process.exitCode.
- Preserve mixed .ts/.js import conventions in context: tsconfig enables TypeScript import extensions and rewriting, while source tests explicitly avoid public provider exports that resolve to unavailable build output.
- For generator changes, edit the command and stub deliberately rather than generated application files; generation calculates destinations in templates and defaults to overwriteExisting=false.
- For codegen changes, preserve indexes-before-boot and router-commit-before-types ordering; maintain JSON serialization parity between standalone codegen and development route handoff.
- Cryptographic adapter changes should retain Legacy cross-version decoding and purpose semantics; relevant specs compare both old-to-new and new-to-old encryption.
- Respect repository formatting configuration: two-space LF text, shared AdonisJS ESLint/Prettier presets, and inherited package TypeScript settings. Broader compiler and lint behavior resides in external presets.
- The publish path has concrete artifact requirements: copied stubs, generated commands/main.js and commands.json, package export targets, and separate TypeScript declarations. A source-only change should be assessed against these boundaries before any authorized release.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 194 | 99% |
| YAML | 6 | docs/config |
| JSON | 4 | docs/config |
| Markdown | 2 | docs/config |
| JavaScript | 1 | 1% |
Start reading here
Probable source entrypoint: index.ts — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (22 files)
Source layout — src/
| Path | Files |
|---|---|
src/assembler_hooks/ | 1 |
src/cli_formatters/ | 1 |
src/helpers/ | 8 |
src/ignitor/ | 4 |
src/test_utils/ | 2 |
src/config_provider.ts | 1 |
src/debug.ts | 1 |
src/exceptions.ts | 1 |
src/types.ts | 1 |
src/utils.ts | 1 |
src/vine.ts | 1 |
Repository structure
| Top-level path | Files |
|---|---|
tests/ | 58 |
modules/ | 40 |
commands/ | 25 |
src/ | 22 |
stubs/ | 21 |
types/ | 14 |
services/ | 13 |
factories/ | 12 |
Docs found: LICENSE.mdREADME.md
Package
package.json — @adonisjs/core v7.5.2, 63 declared dependencies.
@adonisjs/ace@adonisjs/application@adonisjs/assembler@adonisjs/bodyparser@adonisjs/config@adonisjs/encryption@adonisjs/env@adonisjs/eslint-config@adonisjs/events@adonisjs/fold@adonisjs/hash@adonisjs/health
CI & config entrypoints
README.md— Repository readme.github/workflows/labels.yml— GitHub Actions workflow.github/workflows/release.yml— GitHub Actions workflow.github/workflows/test.yml— GitHub Actions workflow.github/workflows/checks.yml— GitHub Actions workflow.github/workflows/stale.yml— GitHub Actions workflowpackage.json— npm scripts: build, citgm, clean, compile, copy:templates, docs, format, index:commands
Structural health signals
Average score 9.2/10 across 96 analyzed source files; 1 hotspot surfaced.
src/cli_formatters/routes_list.ts— 579 lines, score 6.2 (Large file, Deep nesting)modules/ace/codemods.ts— 793 lines, score 6.7 (Large file, Deep nesting)providers/edge_provider.ts— 236 lines, score 6.7 (Deep nesting, Long function/block)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
e1b2357eacc22026-10-01 — feat(codemods): add import alias and directory helpers (#5151)7eeff6a8da6e2026-09-23 — chore(release): 7.5.2184621fc5e302026-09-23 — fix: fail the build when commands index generation fails2b10591a1c6b2026-09-23 — chore: update dependencies4dc76eda68472026-09-23 — chore(release): 7.5.1