adding-a-feature

# Adding a New Tool to @webiny/stdlib This mirrors the "Step-by-step: Adding a New Tool to an Existing Package" section in the repo's `AGENTS.md`, which is the authoritative source — check there if this drifts. First decide which slice the tool belongs in, based on its runtime dependencies: | Uses only JS built-ins / standard lib | → `@webiny/stdlib` root (`src/`) | | Uses `node:*` APIs or Node-only npm packages | → `@webiny/stdlib/node` (`src/node/`) | | Uses `window`, `document`, React, browser APIs | → `@webiny/stdlib/browser` (`src/browser/`) | `src/node/` and `src/browser/` must NOT import from each other. Both may import common code via `~/common/index.js`. Example below: adding `HttpTool` to `@webiny/stdlib/node`. Substitute the appropriate slice and path for your tool. ## Steps 1. **Create the abstraction** at `src/node/features/HttpTool/abstractions/HttpTool.ts`: - Define `interface IHttpTool` with JSDoc on each method. - Export `const HttpTool = createAbstraction<IHttpTool>("Core/HttpTool")`. - Export `namespace HttpTool { export type Interface = IHttpTool }`. 2. **Create the abstraction barrel** at `src/node/features/HttpTool/abstractions/index.ts`: - `export { HttpTool } from "./HttpTool.js";` 3. **Create the implementation** at `src/node/features/HttpTool/HttpTool.ts`: - Rename the token import to avoid a name clash: `import { HttpTool as HttpToolAbstraction } from "./abstractions/HttpTool.js";` - Import cross-slice dependencies via the common barrel: `import { Logger } from "~/common/index.js";` - `class HttpToolImpl implements HttpToolAbstraction.Interface { ... }` - `export const HttpTool = HttpToolAbstraction.createImplementation({ implementation: HttpToolImpl, dependencies: [...] })` - The `dependencies` array order must match the constructor parameter order exactly. 4. **Create the feature** at `src/node/features/HttpTool/feature.ts`: - `export const HttpToolFeature = createFeature({ name: "Core/HttpToolFeature", register(container) { container.register(HttpTool).inSingletonScope(); } })` 5. **Create the feature index** at `src/node/features/HttpTool/index.ts`: - `export { HttpTool } from "./abstractions/index.js";` - `export { HttpToolFeature } from "./feature.js";` - Never re-export the implementation class or the `createImplementation` output. 6. **Create the feature README** at `src/node/features/HttpTool/README.md`: - One-paragraph description — what it does and when to reach for it. - Interface section — the public methods with JSDoc (copy from the abstraction file). - Usage section — two code snippets: DI container wiring, and a `createXxx()` factory function. - Prepend YAML front-matter (`name`, `description`, `context`) so the README is discoverable by the MCP server — see the front-matter block at the top of any existing feature README for the exact shape. - Update the repo root `README.md` table to add a row pointing to the new feature README. 7. **Add to the slice barrel** `src/node/index.ts`: - `export { HttpTool, HttpToolFeature } from "./features/HttpTool/index.js";` 8. **Write tests** at `__tests__/node/HttpTool.test.ts`: - Create a `makeContainer()` helper — see the `testing-patterns` skill. - Cover the happy path and error paths. - Node tests do not need a `// @vitest-environment` directive (only browser tests do). 9. **Run the pre-commit chain** until fully clean: ```sh yarn && yarn adio && yarn format:fix && yarn lint:fix && yarn typecheck && yarn build && yarn test:coverage ``` All steps must pass with zero errors and zero warnings before staging and committing. If any step fails, fix the issue and run the full chain again from the start. ## Conventions to keep in mind throughout - **No default exports.** Always use named exports. - **JSDoc comments are preferred** on interface methods, abstraction types, and public class methods — they're read by both IDE tooling and agents. Don't write comments that just restate the method name. - **Strict TypeScript** — all strict flags in `tsconfig.json` must pass. - **`.js` extensions in package source imports** — under `src/`, `import { Foo } from "./Foo.js"` (not `.ts`); tsgo resolves `.js` to `.ts` at compile time. (Exception: `scripts/`, which runs directly under Node 24 and needs real `.ts` extensions.) - **`node:` prefix for Node built-ins** — `import { readFileSync } from "node:fs"`, never `"fs"`. - **Singletons via DI** — register utils as `.inSingletonScope()` unless there's a reason not to. - **DI token names use `"Domain/ToolName"` format** — `"Core/"` prefix for common utils, `"Node/"` prefix for Node-specific ones. - **Namespace pattern for interface types** — always export `namespace ToolName { export type Interface = IToolName }` alongside the token. See the `di-patterns` skill for the underlying abstraction/implementation/feature mechanics, and AGENTS.md's "Step-by-step: Adding a New Slice to @webiny/stdlib" section if you're adding an entirely new runtime environment rather than a tool within an existing one.