AGENTS.md in serverless/serverless runs 1,721 words across 20 headings.
⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.
JavaScriptCovers
13 of the 20 section tags
In the order a file is read inHeadings
20 headings, in the order the file writes them
01Serverless Framework
02Repository Structure
03Architecture
04Development Setup
05Install dependencies (npm ci never rewrites the lockfile; prefer it over npm install)
06Run the framework locally on a test project
07Code Style
08Formatting Rules
09Linting Commands
10Dependencies
11Testing
12Unit Tests (Run Locally)
13Integration Tests (Live AWS)
14Other Suites
15Testing CLI Behavior Headlessly
16Distribution & Bundling
17Agent Skills (`skills/`)
18CI Pipeline
19Pull Requests & Releases
20Important Files
Commands
23 commands this file writes down
Extracted from the file, verbatimnpm ci
node /path/to/serverless/packages/sf-core/bin/sf-core.js deploy
npm run prettier
npm run prettier:fix
npm run lint
npm run lint:fix
npm run test:unit -w @serverlessinc/sf-core
npm run test:unit -w @serverless/framework
npm run test:unit -w @serverless/mcp
npm test
npm test -w @serverlessinc/sf-core
npm run test:<suite> -w @serverlessinc/sf-core
npm test -w @serverless/mcp
npm test -w @serverless/engine
npm run test:python -w @serverlessinc/sf-core
npm run test:build -w @serverlessinc/sf-core
node packages/sf-core/scripts/lint-skills.js --update
npm-shrinkwrap.json
eslint.config.js
jest
npm run build:devmode:shim -w @serverless/framework
npm install
prettier.js
The file
AGENTS.md
First 160 of 170 lines1# Serverless Framework
2
3Monorepo for the **Serverless Framework** - a command-line tool for deploying serverless applications to AWS Lambda and other managed cloud services, driven by YAML configuration (`serverless.yml`). Development uses Node.js 24 + npm 12 (ES Modules); the shipped CLI supports Node.js >= 18.
4
5## Repository Structure
6
7```text
8├── packages/
9│ ├── sf-core/ # CLI shell: entry point, command router, runners
10│ ├── serverless/ # Traditional framework: AWS provider, plugins, config schema
11│ ├── engine/ # Shared AWS client wrappers used across the CLI
12│ ├── mcp/ # MCP server for AI IDEs
13│ ├── util/ # Shared utilities
14│ ├── standards/ # ESLint and Prettier configs
15│ ├── framework-dist/ # Bundled distribution package (excluded from npm workspaces)
16│ └── sf-core-installer/ # Published to npm as "serverless" (excluded from npm workspaces)
17├── binary-installer/ # Go-based binary installer
18├── docs/sf/ # User-facing documentation (published to serverless.com)
19├── skills/ # Agent Skills shipped inside the CLI (CI-linted)
20└── release-scripts/ # Release automation
21```
22
23### Architecture
24
25- **`packages/sf-core`**: the CLI shell. `bin/sf-core.js` boots `src/lib/router.js`, which dispatches commands to runners in `src/lib/runners/`. Also hosts auth, variable resolvers, observability, and agent-skills logic.
26- **`packages/serverless`**: where most changes land — the AWS provider implementation, all plugins (`lib/plugins/aws/`, `lib/plugins/esbuild/`, ...), and the `serverless.yml` config schema (`lib/config-schema.js`, extended per plugin).
27- **`packages/framework-dist`** and **`packages/sf-core-installer`** are excluded from npm workspaces. `sf-core-installer` is what npm users install as `serverless`; it carries its own `overrides`, its own **published** `npm-shrinkwrap.json`, and its own `.npmrc` — root-level dependency fixes never reach it.
28
29## Development Setup
30
31```bash
32# Install dependencies (npm ci never rewrites the lockfile; prefer it over npm install)
33npm ci
34
35# Run the framework locally on a test project
36cd /path/to/your/test-project
37node /path/to/serverless/packages/sf-core/bin/sf-core.js deploy
38```
39
40## Code Style
41
42### Formatting Rules
43
44- **No semicolons** - Prettier removes them
45- **Single quotes** for strings
46- **2-space indentation**
47- **LF line endings**
48- **ES Modules** - use `import`/`export`, not `require()`
49- Prefer native JavaScript over lodash; use async/await for asynchronous code
50- New examples, fixtures, and snippets use current vendor-recommended idioms (ESM `.mjs` handlers, latest runtimes, AWS SDK v3) — consistency with older repo content is not a reason for legacy style
51
52### Linting Commands
53
54```bash
55npm run prettier # check formatting
56npm run prettier:fix # fix formatting
57npm run lint # run ESLint
58npm run lint:fix # fix lint issues
59```
60
61Gotchas:
62
63- ESLint only lints the explicit path globs listed in `eslint.config.js` — a new package or top-level source directory is silently unlinted until added there.
64- The shared ESLint config (`packages/standards/src/eslint.js`) disables `no-unused-vars` and several other rules — lint will NOT catch unused variables or imports.
65- A husky pre-commit hook runs lint-staged (Prettier on staged JS/TS files), so formatting is partly automated at commit time; still run lint before pushing.
66- Exception to the ES Modules rule: `packages/sf-core-installer` is CommonJS.
67- `.env` files are deliberately NOT gitignored (test fixtures depend on them) — never write real credentials into one.
68
69## Dependencies
70
71- The shipped CLI supports Node.js 18 (`packages/serverless` declares `engines.node: ">=18.0"`). Runtime dependencies must keep Node 18 support even though development uses Node 24. Majors that drop Node 18 are blocked via the ignore list in `.github/dependabot.yml` — check it before bumping; dev-only dependencies may require any Node version.
72- Write `package-lock.json` only with npm 12. npm <= 11 silently drops root `overrides` in workspaces repos (npm/cli#4834). Use `npm ci` for plain installs.
73- `.npmrc` sets `min-release-age=3`: npm versions published less than 3 days ago won't resolve unless you pass `--min-release-age=0` explicitly.
74
75## Testing
76
77### Unit Tests (Run Locally)
78
79```bash
80npm run test:unit -w @serverlessinc/sf-core # jest over packages/sf-core/tests/unit/
81npm run test:unit -w @serverless/framework # jest over packages/serverless/test/unit/
82npm run test:unit -w @serverless/mcp # jest over packages/mcp/tests/ (excluding tests/e2e/)
83npm test # all three unit suites
84```
85
86Note the inconsistent directory naming: `tests/` in sf-core, `test/` in serverless — easy to misplace new tests.
87
88Always invoke Jest via the npm scripts, not bare `jest` — the scripts set `--experimental-vm-modules`, required for ESM.
89
90### Integration Tests (Live AWS)
91
92Integration tests deploy real AWS stacks. They run in CI on non-draft PRs and can be run locally given AWS credentials plus the prerequisite resources described in [TESTING.md](TESTING.md).
93
94```bash
95npm test -w @serverlessinc/sf-core # integration suite (excludes domains and mcp)
96npm run test:<suite> -w @serverlessinc/sf-core # targeted suite
97```
98
99Targeted suites include: `simple:nodejs`, `simple:python`, `simple:compose`, `simple:dashboard`, `simple:resolvers`, `resolvers`, `esbuild`, `sam`, `sandboxes`, `state`, `deployment-bucket`, `license-key`, `domains`, `mcp`, `compose:dev`, `compose:subset`. Prefer the targeted suite covering the touched area. Two suites are excluded from `npm test`: `domains` (not run by any CI workflow — only when invoked explicitly) and `mcp` (run by the path-filtered `CI: MCP Servers` workflow; only its `mcp-auth.test.js` suite needs the Cognito prerequisite from [TESTING.md](TESTING.md) — absent that, that suite skips while the rest runs). Any other new directory under `tests/integration/` joins `npm test` automatically, so an expensive new suite has to opt out the same way.
100
101Conventions: each suite pairs `<name>.test.js` with a sibling `fixture/` directory holding the service under test — **one fixture directory per test file**, since jest parallelizes test files with no worker cap and two files deploying from one directory would race over `.serverless/`, `node_modules/` and any staged artifact; reuse the shared helpers in `packages/sf-core/tests/utils/` (`runSfCore.js`, `testUtils.js` — e.g. `fetchWithRetry` for eventually-consistent endpoints) rather than hand-rolling CLI invocation. Fixtures must not list legacy bundler plugins (`serverless-esbuild`, `serverless-webpack`, `serverless-plugin-typescript`, `serverless-bundle`) — those throw `PLUGIN_TYPESCRIPT_CONFLICT` unless `build.esbuild: false` is set.
102
103Dev-mode tests need the gitignored shim built first: `npm run build:devmode:shim -w @serverless/framework` (CI does this as a separate step).
104
105New integration tests must be self-cleaning (deploy → exercise → teardown, even on failure), use unique stack names so parallel runs are safe, and contain no secrets or account IDs in fixtures or assertions.
106
107### Other Suites
108
109```bash
110npm test -w @serverless/mcp # mcp tests (NOT run by any CI workflow)
111npm test -w @serverless/engine # engine unit tests
112npm run test:python -w @serverlessinc/sf-core # python plugin tests
113npm run test:build -w @serverlessinc/sf-core # packaging smoke + skills-packaging check (not in CI)
114cd binary-installer && go test ./... && make build-prod # Go installer
115```
116
117The CI python job is path-filtered (runs only when python plugin paths change) — failures can sit unnoticed on main until a PR touches those paths. `packages/util` has no tests at all: util changes are exercised only through its consumers' suites.
118
119### Testing CLI Behavior Headlessly
120
121Never drive the CLI through a pty (`script`, `pty.spawn`): a pty is indistinguishable from a real terminal, so spinners animate and interactive prompts open. Use plain pipes — the interactivity gate is typically `stdin.isTTY && stdout.isTTY && !CI`.
122
123## Distribution & Bundling
124
125The released CLI is bundled with esbuild into a single file. Standard `import`/`export` modules are bundled automatically, but **non-JS assets and anything loaded via a `__dirname`-relative path** (JSON, `.py` files, templates, spawned scripts) must be explicitly registered in `packages/sf-core/scripts/prepareDistributionTarballs.js` — otherwise the code works from source and breaks in the release.
126
127Keep `esbuild` listed in `external` in `packages/sf-core/esbuild.js` — bundling esbuild's own code breaks the worker it spawns (see the comment there).
128
129`packages/framework-dist` is an empty shell in git: its contents are generated at build time. The npm `serverless` package (`sf-core-installer`) only downloads the Go launcher binary, which resolves `frameworkVersion` per project, downloads the release tarball built from `framework-dist` into `~/.serverless/releases/<version>`, and runs `npm install` there — the published tarball contents directly become end-user installs. Launcher behavior (version resolution, caching, 24h update throttle) is documented in `binary-installer/README.md`.
130
131## Agent Skills (`skills/`)
132
133Any content change to a skill requires bumping its `metadata.version` and regenerating the manifest, or CI fails:
134
135```bash
136node packages/sf-core/scripts/lint-skills.js --update
137```
138
139Commit `skills/manifest.json` alongside. Aux files are never deleted from user installs — add or rename files instead of repurposing an existing filename. See `skills/README.md` for the full contract.
140
141## CI Pipeline
142
143CI runs on pull requests targeting `main`, on Node.js 24.x:
144
145- **CI: Framework CLI** — Lint, Test: Engine, Test: Framework (unit + integration). Skipped entirely for docs-only changes (`paths-ignore: docs/**`) and for draft PRs.
146- **CI: Binary Installer** — Go build and tests; runs only when `binary-installer/**` changes
147- **CI: Python Requirements** — path-filtered (see Testing above)
148- **CI: MCP Servers** — the live `mcp` suite; path-filtered to the MCP plugin, the api-gateway and esbuild seams, and the MCP tests/fixtures. GitHub Actions has no job-level path filter, which is why this and the python suite each live in their own workflow file.
149
150The `release-*.yml` workflows run only on push to main or manual dispatch — they are never exercised by PR CI, so review changes to them with extra care. `release-framework.yml` is additionally path-filtered to `packages/{sf-core,serverless,engine,mcp}/**`: changes elsewhere (e.g. `packages/util`) never trigger a release build on their own.
151
152## Pull Requests & Releases
153
154- PRs are **squash-merged**; the PR title becomes the commit message. Use conventional format: `type(scope): description` — imperative mood, no trailing period, ~72 chars max. Types: feat, fix, perf, docs, refactor, test, ci, chore.
155- Any `feat:` triggers a minor release; only `fix:`/`chore:` means a patch. See [VERSIONING.md](VERSIONING.md) for the full semver interpretation — notably, changes to CLI output structure and to generated CloudFormation count as **breaking**.
156- Non-trivial features and fixes should have an open issue first — see [CONTRIBUTING.md](CONTRIBUTING.md).
157- User-facing changes (behavior, config surface, CLI output) should update the docs in `docs/sf/` in the same PR.
158- The root `README.md` is copied into the published npm package at release time — edits to it are user-facing.
159- Every push to `main` touching the release-relevant packages automatically publishes a **canary** build, versioned by git short SHA (users opt in with `frameworkVersion: canary`) — code merged to main is live on the canary channel within minutes, so main must always be releasable.
160- A stable release bumps the version in BOTH `packages/sf-core-installer/package.json` and `packages/sf-core/package.json`, in a PR titled exactly `chore: release x.x.x`; on merge, CI tags `sf-core@x.y.z` (use these tags to diff what shipped since the last release). npm is a secondary distribution channel; the curl installer (`install.serverless.com`) is primary. Full pipeline: [RELEASE_PROCESS.md](RELEASE_PROCESS.md).
10 more lines are in the file. Read the raw file.
This listing
Whoever runs serverless/serverless can claim it
This is yours? Claim this config and we will write to you when the measurement moves. The check is one token placed where only you can place it, and there is no account and no password.