Files
2db78cdcd8 Upgrade ESLint v9 → v10 (+ typescript-eslint 8.65, pnpm catalog cleanup) (#39421)
## 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
2026-07-28 15:30:40 -07:00
..
…

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:

  1. Create samples in TypeScript under the package's samples-dev/ directory
  2. Add a sample.env listing all the environment variables that are needed by the samples of this package. Customers can adopt it into their .env file when running samples.
  3. After testing is done on your samples, run npx dev-tool samples publish from 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 the samples/ 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/.