## Summary Upgrades the repo from ESLint **v9 → v10** (latest 10.x, resolves 10.8.0) and bumps `typescript-eslint` / `@typescript-eslint/*` from `~8.60.0` → `~8.65.0`. The repo already uses flat config (`eslint.config.mjs`) via the internal `@azure/eslint-plugin-azure-sdk`, so this is a version-bump + compatibility effort, not a config migration. Follow-up commits tidy up dependency declarations (pnpm catalog + redundant `@types/*`), address review feedback, and fix the real-world v10 lint breaks surfaced by CI. **Repo-wide lint verified:** `turbo lint --continue` across the whole workspace → **468/468 packages pass, 0 errors** (remaining `✖` are warnings only — the intentionally-downgraded rules). ESLint version is controlled centrally by the pnpm catalog in `pnpm-workspace.yaml`. ## Commit 1 — ESLint v9 → v10 + typescript-eslint 8.65 - **pnpm catalog**: `eslint ^9.39.1 → ^10.x`. - `@eslint/js ^9 → ^10.0.1`; `eslint-plugin-promise ^7.2.1 → ^7.3.0` (adds eslint `^10` peer); plugin `peerDependencies.eslint ^9.22.0 → ^10.0.0`. - `typescript-eslint` / `@typescript-eslint/*` `~8.60.0 → ~8.65.0` across the plugin, tooling packages, and `samples/frameworks/react/ts`. - **`eslint-plugin-import` peer blocker** (its latest still caps eslint at `^9`) resolved via pnpm `peerDependencyRules.allowedVersions` — only `import/no-extraneous-dependencies` is consumed and it works functionally under v10 (chosen over switching to `eslint-plugin-import-x` for lower risk / zero code change). - **`engines.node`** tightened to `>=22.13` (root) / `>=22.13.0` (plugin), matching ESLint 10's Node floor. - **ESLint 10 compat fix** in `src/utils/verifiers.ts`: `RuleFixer.replaceText` now hard-asserts a string, so a lying `(expected as string)` cast was replaced with `String(expected)` (2 fixers). - **3 new v10 `eslint:recommended` rules** (`preserve-caught-error`, `no-useless-assignment`, `no-unassigned-vars`) downgraded to `"warn"` in `eslint-customized.ts` with a justification comment, so the bump doesn't break `lint` repo-wide at once (mirrors the existing `no-param-reassign` precedent; can be promoted back to `error` after cleanup — tracked in #39423). **Validation:** plugin build OK; **vitest 703/703 pass**; `@azure/storage-queue` lint **0 errors, 51 warnings**. ## Commit 2 — pnpm catalog cleanup + redundant `@types/*` removal - Move **`@eslint/js`** and **`typescript-eslint`** into the `pnpm-workspace.yaml` default catalog and reference them via `"catalog:"` in workspace members (`eslint-plugin-azure-sdk`, `dev-tool`, `warp`, `vite-plugin-browser-test-map`, `turborepo-remote-cache`). - **`eng/tools/ci-runner`** is **not** a pnpm workspace member, so it keeps **direct** versions (a `catalog:` ref would not resolve there). The v7-pinned `js-sdk-release-tools` breaking-change-detector is left untouched. - Remove 3 redundant `@types/*` devDependencies from `eslint-plugin-azure-sdk` (`@types/eslint` — which was duplicated in both `dependencies` and `devDependencies` — plus `@types/eslint-config-prettier`), now that `eslint@10` and `eslint-config-prettier@10` ship their own bundled type definitions. ## Commit 3 — review feedback: bump the `eslint` runtime to v10 too - Two packages had `@eslint/js` bumped to v10 but still declared the `eslint` **runtime** at `^9`. Fixed: `turborepo-remote-cache` → `eslint: "catalog:"`; `ci-runner` → direct `eslint: ^10.8.0` (not a workspace member). - Catalog `eslint` pinned to the latest 10.x (`^10.8.0`); catalog now resolves eslint 10.8.0 everywhere. ## Commit 4 — repo-wide lint fix: `no-useless-assignment` in dev-tool Broad CI linting surfaced one real v10 error the shared `warn` downgrade did **not** cover: tooling packages (`dev-tool`, `warp`, `turborepo-remote-cache`, `ci-runner`, and the plugin itself) use **standalone** `eslint.config.mjs` files that apply `@eslint/js` `recommended` **directly**, bypassing the shared `eslint-customized.ts` overrides — so the 3 new rules fire as **errors** there, not warnings. - Fixed the single violation: `common/tools/dev-tool/.../checkNodeVersions.ts` dropped a redundant `= undefined` initializer on `artifactURL` (every code path reassigns or throws before it's read). Lint + `tsc` both clean. - Audited every standalone-config package in CI lint scope — `warp`, `vite-plugin-browser-test-map`, `turborepo-remote-cache`, and `eslint-plugin-azure-sdk` all lint clean; `dev-tool` was the only error. ## Commit 5 — `no-shadow-restricted-names` now reports `globalThis` (v10 change) A second CI run surfaced a different v10 behavior change: `no-shadow-restricted-names`'s `reportGlobalThis` option flipped its default from `false` → `true`, so it now flags `declare const globalThis` **ambient TypeScript declarations** (used to narrowly type `globalThis.*` without pulling in full lib types) as shadowing a restricted name. This broke `@typespec/ts-http-runtime` lint (`src/util/uuidUtils.ts` + `uuidUtils-react-native.mts`, 2 errors — the only two such declarations in the repo). - Restored the v9 behavior in the shared `eslint-customized.ts` via `"no-shadow-restricted-names": ["error", { reportGlobalThis: false }]`, keeping the rest of the rule active (still catches shadowing of `NaN`, `undefined`, `Infinity`, `eval`, `arguments`). This is the fix ESLint's own migration guide documents for the ambient-declaration case. ## Notes - The 3 new v10 recommended rules are intentionally `warn`, not `off`, for packages on the shared config — they stay visible for later cleanup (#39423). - The other `[ELIFECYCLE] Command failed` lines in the CI logs were turbo fail-fast casualties (different set each run), not independent errors — confirmed by linting them directly (all pass) and by the full-repo `turbo lint` (468/468). - No source/runtime behavior changes beyond the `verifiers.ts` compat fix and the dev-tool `artifactURL` cleanup; the rest is dependency + config metadata. ## Commit 6 — review feedback: downgrade the 3 new v10 rules in the `internal` config too _Copilot agent :copilot: (on behalf of @jeremymeng):_ Review feedback surfaced one more path the shared `eslint-customized.ts` warning downgrades did **not** reach: the `internal` config (in `src/configs/index.ts`) builds its own array that spreads `eslint.configs.recommended` but never includes `eslintCustomized`, so `preserve-caught-error`, `no-useless-assignment`, and `no-unassigned-vars` stayed as **errors** for consumers of `configs.internal` (e.g. `sdk/test-utils/recorder`) — contrary to the repo-wide warning-only migration intent. - Added the three `"warn"` downgrades directly to the `internal` config's inline `rules` block so it matches the `recommended` config. Scoped to just those three rules; no other restructuring. --------- Co-authored-by: Copilot App <[email protected]> Copilot-Session: cf6320ed-d2d6-420c-8188-6a63a557ca4b
Samples, Snippets, and How-To Guides
Developers like to learn by looking at code, and so the Azure SDK comes with many samples in the form of short code snippets, sample applications, and how-to guides. This document describes where to find all these resources.
Structure of the Repository
The Azure SDK repository is organized in the following folder structure, with the main sample locations highlighted using bold font.
/samples(this folder)README.md(this file)- ... (subdirectories for examples that aren't specific to only one package)
/sdk(folder containing sources for all SDK packages)/<service>(e.g. storage)/<package>(e.g.@azure/storage-blob)README.md(package READMEs contain "hello world" code snippets)/samples/typescript(package-specific samples in TypeScript)/javascript(package-specific samples in JavaScript using CommonJS)
/src/tests
Getting Started Samples
Each package folder contains a package-specific README.md file. Most of these README files contain samples illustrating basic usage of the the APIs contained in the package. For example, you can find the Getting Started samples for the @azure/storage-blob package here.
Package Samples and How-To Guides
Each package folder contains a subfolder called samples with additional code samples in the typescript and javascript subfolder. Corresponding files (i.e. samples/typescript/src/helloWorld.ts and samples/javascript/helloWorld.js) in the TypeScript and JavaScript directories are functionally equivalent. These samples may be viewed in GitHub or browsed on the Sample Browser at learn.microsoft.com/samples by selecting the product and language combination that you wish to view samples for.
Authoring Package Samples
For the majority of our packages we use the following workflow to develop samples:
- Create samples in TypeScript under the package's
samples-dev/directory - Add a
sample.envlisting all the environment variables that are needed by the samples of this package. Customers can adopt it into their.envfile when running samples. - After testing is done on your samples, run
npx dev-tool samples publishfrom the package directory (where the package.json is located), not from the repository root. This command generates both TypeScript and JavaScript versions of the samples under thesamples/folder.
Sample Configuration in package.json
The //sampleConfiguration section in the package.json holds the package-level sample configuration. Here is an example
"//sampleConfiguration": {
"productName": "Azure Schema Registry",
"productSlugs": [
"azure",
"azure-schema-registry"
],
"requiredResources": {
"Azure Schema Registry resource": "https://aka.ms/schemaregistry"
}
},
If you do not want to publish samples to learn.microsoft.com, add "disableDocsMs": true in the sample configuration.
Azure SDK Metadata Tags for Samples
Files under samples-dev can also be configured individually with the following tags.
The @summary tag in JSDoc comments is used to provide a description of the sample, which will be extracted and included in the generated sample index in the sample README.md.
The following tags can be used in the first doc comment after the license header to customize the publication of samples
-
@azsdk-weight: this gives a weight to the sample. It is used to control the ordering of samples in the table of the sample README.md. Samples with larger weights appear before samples with smaller weights. A default value of zero is used if weight is not specified. -
@azsdk-ignore: this causes the file to be skipped entirely (will not be included in publication) -
@azsdk-util: this causes the file to be omitted from the generated sample index in the sample README.md. -
@azsdk-skip-javascript: this causes the file to skip JavaScript output. Useful when sample code doesn't have supported syntax in the CommonJS version.
Global Samples
Samples that apply to every package or to no package in particular are located in subdirectories within the root /samples directory. For example, the /samples/Bundling directory contains sample code illustrating how to configure package bundling tools to work with the Azure SDK for JS packages:
/samples/Bundling/parcel(samples for using the SDK packages with parcel)/js(in JavaScript, using CommonJS)/ts(in TypeScript)
/rollup(the same, with rollup)/webpack(the same, with webpack)
(The rollup and webpack directories also have js and ts subdirectories for JavaScript and TypeScript respectively.)
For more information on package bundling, see /documentation/Bundling.md.
Sample Applications
Sometimes we want to illustrate how several APIs or even packages work together in a context of a more complete program. For these cases, we created sample applications. These application samples are located in other repositories and, like the package-specific samples, may be viewed on https://learn.microsoft.com/samples/.