Package Scaffolding

All these paths are included in pnpm-workspace.yaml. No workspace registration is needed.

Directory Structure

my-package/
├── api-extractor/
│   ├── api-extractor.current.json
│   ├── api-extractor.legacy.json
│   ├── api-extractor-lint-public.esm.json
│   ├── api-extractor-lint-public.cjs.json
│   ├── api-extractor-lint-legacy.esm.json
│   ├── api-extractor-lint-legacy.cjs.json
│   └── api-extractor-lint-bundle.json
├── api-report/                          # Generated, committed
│   └── (created after first build)
├── src/
│   ├── cjs/
│   │   └── package.json
│   ├── test/
│   │   ├── tsconfig.json
│   │   ├── tsconfig.cjs.json
│   │   └── *.spec.ts
│   ├── index.ts
│   └── internal.ts
├── .mocharc.cjs
├── eslint.config.mts
├── package.json
├── test-config.json
├── tsconfig.json
└── tsconfig.cjs.json

Required Files

package.json

Adapt the version, name, description, and directory path. Match devDependency versions to an existing peer package.

{
  "name": "@fluidframework/my-package",
  "version": "2.90.0",
  "description": "Description of the package",
  "homepage": "https://fluidframework.com",
  "repository": {
    "type": "git",
    "url": "https://github.com/microsoft/FluidFramework.git",
    "directory": "packages/category/my-package"
  },
  "license": "MIT",
  "author": "Microsoft and contributors",
  "sideEffects": false,
  "type": "module",
  "exports": {
    ".": {
      "import": {
        "types": "./lib/public.d.ts",
        "default": "./lib/index.js"
      },
      "require": {
        "types": "./dist/public.d.ts",
        "default": "./dist/index.js"
      }
    },
    "./internal": {
      "import": {
        "types": "./lib/index.d.ts",
        "default": "./lib/index.js"
      },
      "require": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      }
    }
  },
  "main": "lib/index.js",
  "types": "lib/public.d.ts",
  "scripts": {
    "api": "fluid-build . --task api",
    "api-extractor:commonjs": "flub generate entrypoints --outDir ./dist",
    "api-extractor:esnext": "flub generate entrypoints --outDir ./lib --node10TypeCompat",
    "build": "fluid-build . --task build",
    "build:api-reports": "concurrently \"npm:build:api-reports:*\"",
    "build:api-reports:current": "api-extractor run --local --config api-extractor/api-extractor.current.json",
    "build:commonjs": "fluid-build . --task commonjs",
    "build:compile": "fluid-build . --task compile",
    "build:docs": "api-extractor run --local",
    "build:esnext": "tsc --project ./tsconfig.json",
    "build:test": "npm run build:test:esm && npm run build:test:cjs",
    "build:test:cjs": "fluid-tsc commonjs --project ./src/test/tsconfig.cjs.json",
    "build:test:esm": "tsc --project ./src/test/tsconfig.json",
    "check:are-the-types-wrong": "attw --pack .",
    "check:biome": "biome check .",
    "check:exports": "concurrently \"npm:check:exports:*\"",
    "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json",
    "check:exports:cjs:public": "api-extractor run --config api-extractor/api-extractor-lint-public.cjs.json",
    "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json",
    "clean": "rimraf --glob dist lib \"*.d.ts\" \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
    "eslint": "eslint --quiet --format stylish src",
    "eslint:fix": "eslint --quiet --format stylish src --fix --fix-type problem,suggestion,layout",
    "format": "npm run format:biome",
    "format:biome": "biome check . --write",
    "lint": "fluid-build . --task lint",
    "lint:fix": "fluid-build . --task eslint:fix --task format",
    "test": "npm run test:mocha",
    "test:coverage": "c8 npm test",
    "test:mocha": "npm run test:mocha:esm && echo skipping cjs to avoid overhead",
    "test:mocha:cjs": "cross-env FLUID_TEST_MODULE_SYSTEM=CJS mocha",
    "test:mocha:esm": "mocha",
    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && npm run place:cjs:package-stub",
    "place:cjs:package-stub": "copyfiles -f ./src/cjs/package.json ./dist",
    "typetests:gen": "flub generate typetests --dir . -v",
    "typetests:prepare": "flub typetests --dir . --reset --previous --normalize"
  },
  "c8": {
    "all": true,
    "cache-dir": "nyc/.cache",
    "exclude": ["src/test/**/*.*ts", "lib/test/**/*.*js"],
    "exclude-after-remap": false,
    "include": ["src/**/*.*ts", "lib/**/*.*js"],
    "report-dir": "nyc/report",
    "reporter": ["cobertura", "html", "text"],
    "temp-directory": "nyc/.nyc_output"
  },
  "dependencies": {},
  "devDependencies": {
    "@arethetypeswrong/cli": "^0.18.2",
    "@biomejs/biome": "~1.9.3",
    "@fluid-tools/build-cli": "^0.63.0",
    "@fluidframework/build-common": "^2.0.3",
    "@fluidframework/build-tools": "^0.63.0",
    "@fluidframework/eslint-config-fluid": "workspace:~",
    "@microsoft/api-extractor": "7.52.11",
    "@types/mocha": "^10.0.10",
    "@types/node": "~20.19.30",
    "c8": "^10.1.3",
    "concurrently": "^9.2.1",
    "copyfiles": "^2.4.1",
    "cross-env": "^10.1.0",
    "eslint": "~9.39.1",
    "mocha": "^11.7.5",
    "mocha-multi-reporters": "^1.5.1",
    "rimraf": "^6.1.3",
    "typescript": "~5.4.5"
  },
  "fluidBuild": {
    "tasks": {}
  },
  "typeValidation": {
    "broken": {},
    "entrypoint": "public"
  }
}

Key conventions:

• Use workspace:~ for internal Fluid dependencies
• Match the monorepo version (2.90.0 or current)
• Use "type": "module" for ESM-first
• Internal dependencies go in dependencies, build tools in devDependencies

tsconfig.json (ESM)

Adjust the extends path based on package depth relative to common/build/build-common/.

{
  "extends": "../../../common/build/build-common/tsconfig.node16.json",
  "include": ["src/**/*"],
  "exclude": ["src/test/**/*"],
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./lib"
  }
}

tsconfig.cjs.json (CJS)

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist"
  }
}

src/index.ts

/*!
 * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
 * Licensed under the MIT License.
 */

export type { IMyInterface } from "./myInterface.js";
export { MyClass } from "./myClass.js";

Tag every export with a release tag (@public, @beta, @alpha, @internal) in the source file where it's defined.

src/internal.ts

Re-exports everything from index.ts plus any internal-only exports:

/*!
 * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
 * Licensed under the MIT License.
 */

export * from "./index.js";

src/cjs/package.json

{
  "type": "commonjs"
}

This gets copied to dist/ during build to mark CJS output.

eslint.config.mts

Adjust the import path depth to reach common/build/eslint-config-fluid/.

import type { Linter } from "eslint";
import { strict } from "../../../common/build/eslint-config-fluid/flat.mts";

const config: Linter.Config[] = [
  ...strict,
];

export default config;

Available presets: strict (core packages), recommended (mid-level), minimalDeprecated (minimal).

.mocharc.cjs

"use strict";

const testCJS = process.env.FLUID_TEST_MODULE_SYSTEM === "CJS";
const outputFilePrefix = testCJS ? "CJS-" : "";
const suiteName = "@fluidframework/my-package" + (testCJS ? " - CJS" : "");

module.exports = {
  spec: testCJS ? "dist/test/**/*.spec.*js" : "lib/test/**/*.spec.*js",
  recursive: true,
  reporter: "mocha-multi-reporters",
  "reporter-options": [
    `configFile=test-config.json,cmrOutput=xunit+output+${outputFilePrefix}:xunit+suiteName+${suiteName}`,
  ],
  "unhandled-rejections": "strict",
};

test-config.json

{
  "reporterEnabled": "spec, xunit",
  "xunitReporterOptions": {
    "output": "nyc/{id}junit-report.xml",
    "suiteName": "{id}"
  }
}

src/test/tsconfig.json

Adjust the extends path depth.

{
  "extends": "../../../../common/build/build-common/tsconfig.test.node16.json",
  "compilerOptions": {
    "rootDir": "./",
    "outDir": "../../lib/test",
    "types": ["mocha", "node"]
  },
  "include": ["./**/*"],
  "references": [
    { "path": "../.." }
  ]
}

API Extractor Configs

api-extractor/api-extractor.current.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "extends": "<projectFolder>/../../../common/build/build-common/api-extractor-report.esm.current.json",
  "mainEntryPointFilePath": "<projectFolder>/lib/public.d.ts"
}

api-extractor/api-extractor.legacy.json

Only needed if the package has a legacy API surface. Otherwise omit.

{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "extends": "<projectFolder>/../../../common/build/build-common/api-extractor-report.esm.legacy.json"
}

api-extractor/api-extractor-lint-public.esm.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
  "mainEntryPointFilePath": "<projectFolder>/lib/public.d.ts"
}

api-extractor/api-extractor-lint-public.cjs.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
  "mainEntryPointFilePath": "<projectFolder>/dist/public.d.ts"
}

api-extractor/api-extractor-lint-bundle.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.json",
  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts"
}

Add additional lint configs for ./legacy, ./beta, or ./alpha paths if the package exposes them.

Register in layerInfo.json

Add the package to the appropriate group and layer in layerInfo.json at the repo root:

"LayerName": {
  "packages": ["@fluidframework/my-package"],
  "deps": ["Core-Interfaces", "Core-Utils"]
}

Choose dependencies carefully — they define the allowed dependency graph. Run flub check layers --info layerInfo.json to validate.

Post-Creation Steps

1. Run pnpm install to update the workspace lockfile
2. Build the package: fluid-build packages/category/my-package --task build
3. Generate API reports: cd packages/category/my-package && npm run build:api-reports
4. Commit the generated api-report/ files
5. Run flub check policy to verify repo policy compliance
6. Run flub check layers --info layerInfo.json to verify layer dependencies

Biome Formatting

Packages inherit from the root biome.jsonc automatically. No per-package config needed unless you need overrides (rare).

Default formatting: tabs, 95-char line width, double quotes, semicolons always, trailing commas.

Checklist

• Directory created in correct location
• package.json with correct name, version, exports, scripts, and dependencies
• tsconfig.json extending tsconfig.node16.json
• tsconfig.cjs.json extending local tsconfig.json
• src/index.ts with public exports
• src/internal.ts re-exporting index
• src/cjs/package.json with "type": "commonjs"
• eslint.config.mts extending strict
• .mocharc.cjs with correct package name
• test-config.json for test reporters
• src/test/tsconfig.json for test compilation
• api-extractor/ configs (current + lint variants)
• Package registered in layerInfo.json
• pnpm install run to update lockfile
• First build succeeds
• api-report/ generated and committed
• flub check policy passes
• flub check layers passes