diff --git a/ClientRequirements.md b/ClientRequirements.md index 06da7d126aec..f4536dde2420 100644 --- a/ClientRequirements.md +++ b/ClientRequirements.md @@ -1,5 +1,10 @@ # Platform Requirements for Fluid Framework Client Packages + + + + + These are the platform requirements for the current version of Fluid Framework Client Packages. These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. For Long Term Support (LTS) versions this can require supporting these platforms for several years. @@ -41,3 +46,7 @@ Node10 resolution is not supported as it does not support Fluid Framework's API Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + + + + diff --git a/experimental/dds/ot/ot/README.md b/experimental/dds/ot/ot/README.md index 0c78bbc3d015..9305198b0146 100644 --- a/experimental/dds/ot/ot/README.md +++ b/experimental/dds/ot/ot/README.md @@ -30,6 +30,50 @@ npm i @fluid-experimental/ot API documentation for **@fluid-experimental/ot** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/experimental/framework/data-objects/README.md b/experimental/framework/data-objects/README.md index 8209e9c52c8b..567e50b176aa 100644 --- a/experimental/framework/data-objects/README.md +++ b/experimental/framework/data-objects/README.md @@ -32,6 +32,50 @@ npm i @fluid-experimental/data-objects API documentation for **@fluid-experimental/data-objects** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/experimental/framework/tree-react-api/README.md b/experimental/framework/tree-react-api/README.md index fcabdf021b87..877985d1a05d 100644 --- a/experimental/framework/tree-react-api/README.md +++ b/experimental/framework/tree-react-api/README.md @@ -52,6 +52,50 @@ npm i @fluid-experimental/tree-react-api API documentation for **@fluid-experimental/tree-react-api** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/dds/cell/README.md b/packages/dds/cell/README.md index 32db8b292c4e..9536a1ec7e39 100644 --- a/packages/dds/cell/README.md +++ b/packages/dds/cell/README.md @@ -30,6 +30,50 @@ npm i @fluidframework/cell API documentation for **@fluidframework/cell** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/dds/counter/README.md b/packages/dds/counter/README.md index 137fa75c2c77..88b0b092f719 100644 --- a/packages/dds/counter/README.md +++ b/packages/dds/counter/README.md @@ -182,6 +182,50 @@ Since `updateCounterValueLabel` is listening for all `incremented` events, the v API documentation for **@fluidframework/counter** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/dds/ink/README.md b/packages/dds/ink/README.md index f90be8b2588a..f571c1a5763b 100644 --- a/packages/dds/ink/README.md +++ b/packages/dds/ink/README.md @@ -32,6 +32,50 @@ npm i @fluid-experimental/ink API documentation for **@fluid-experimental/ink** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/dds/map/README.md b/packages/dds/map/README.md index c65c18bd8cea..b8cfde2b8949 100644 --- a/packages/dds/map/README.md +++ b/packages/dds/map/README.md @@ -94,6 +94,50 @@ To "navigate" the subdirectory structure, `IDirectory` provides a `getWorkingDir API documentation for **@fluidframework/map** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/dds/merge-tree/README.md b/packages/dds/merge-tree/README.md index 111fef67bbac..49e34afe6655 100644 --- a/packages/dds/merge-tree/README.md +++ b/packages/dds/merge-tree/README.md @@ -142,6 +142,50 @@ remote clients and should be ignored when processing remote ops. API documentation for **@fluidframework/merge-tree** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/dds/pact-map/README.md b/packages/dds/pact-map/README.md index b94712ed39da..005325888873 100644 --- a/packages/dds/pact-map/README.md +++ b/packages/dds/pact-map/README.md @@ -30,6 +30,50 @@ npm i @fluid-experimental/pact-map API documentation for **@fluid-experimental/pact-map** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/dds/sequence/README.md b/packages/dds/sequence/README.md index cddf3f61220d..554c221d44ee 100644 --- a/packages/dds/sequence/README.md +++ b/packages/dds/sequence/README.md @@ -635,6 +635,50 @@ For further reading on attribution, see the [@fluid-experimental/attributor READ API documentation for **@fluidframework/sequence** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/dds/task-manager/README.md b/packages/dds/task-manager/README.md index 6ed57f7e727d..dc7ea9c4e3f4 100644 --- a/packages/dds/task-manager/README.md +++ b/packages/dds/task-manager/README.md @@ -34,6 +34,50 @@ To access the `legacy` APIs, import via `@fluidframework/task-manager/legacy`. API documentation for **@fluidframework/task-manager** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/dds/tree/README.md b/packages/dds/tree/README.md index 9488b2d1d5bf..714748f390d1 100644 --- a/packages/dds/tree/README.md +++ b/packages/dds/tree/README.md @@ -427,6 +427,50 @@ This is important for performance/scalability and might be how we do virtualizat API documentation for **@fluidframework/tree** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/drivers/tinylicious-driver/README.md b/packages/drivers/tinylicious-driver/README.md index 822b86f44c41..60c3ad35a7a8 100644 --- a/packages/drivers/tinylicious-driver/README.md +++ b/packages/drivers/tinylicious-driver/README.md @@ -25,6 +25,50 @@ npm i @fluidframework/tinylicious-driver API documentation for **@fluidframework/tinylicious-driver** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/framework/data-object-base/README.md b/packages/framework/data-object-base/README.md index 528583bc10e1..bb6323a87296 100644 --- a/packages/framework/data-object-base/README.md +++ b/packages/framework/data-object-base/README.md @@ -32,6 +32,50 @@ npm i @fluid-experimental/data-object-base API documentation for **@fluid-experimental/data-object-base** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/framework/fluid-framework/README.md b/packages/framework/fluid-framework/README.md index 106a23d9ccab..ab07875c3c60 100644 --- a/packages/framework/fluid-framework/README.md +++ b/packages/framework/fluid-framework/README.md @@ -75,6 +75,50 @@ Check out the [Hello World tutorial](https://fluidframework.com/docs/start/tutor API documentation for **fluid-framework** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/loader/driver-utils/README.md b/packages/loader/driver-utils/README.md index eeefcf9139bf..166c85d1580c 100644 --- a/packages/loader/driver-utils/README.md +++ b/packages/loader/driver-utils/README.md @@ -36,6 +36,50 @@ To access the `legacy` APIs, import via `@fluidframework/driver-utils/legacy`. API documentation for **@fluidframework/driver-utils** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/loader/test-loader-utils/README.md b/packages/loader/test-loader-utils/README.md index d7ff51d5eba1..a79902e18806 100644 --- a/packages/loader/test-loader-utils/README.md +++ b/packages/loader/test-loader-utils/README.md @@ -10,6 +10,50 @@ Test utilities for the Fluid Framework Loader. Includes mock implementations of **NOTE: This package is private to the `@microsoft/fluid-framework` repository.** **It is not published, and therefore may only be used as a dev dependency.** +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/runtime/container-runtime-definitions/README.md b/packages/runtime/container-runtime-definitions/README.md index 85ea475a8038..10e498ad895e 100644 --- a/packages/runtime/container-runtime-definitions/README.md +++ b/packages/runtime/container-runtime-definitions/README.md @@ -36,6 +36,50 @@ To access the `legacy` APIs, import via `@fluidframework/container-runtime-defin API documentation for **@fluidframework/container-runtime-definitions** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/runtime/container-runtime/README.md b/packages/runtime/container-runtime/README.md index a809acc15b98..f3942ba6390a 100644 --- a/packages/runtime/container-runtime/README.md +++ b/packages/runtime/container-runtime/README.md @@ -79,6 +79,50 @@ To access the `legacy` APIs, import via `@fluidframework/container-runtime/legac API documentation for **@fluidframework/container-runtime** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/runtime/runtime-utils/README.md b/packages/runtime/runtime-utils/README.md index 5bec6e05ae42..d523d914f565 100644 --- a/packages/runtime/runtime-utils/README.md +++ b/packages/runtime/runtime-utils/README.md @@ -36,6 +36,50 @@ To access the `legacy` APIs, import via `@fluidframework/runtime-utils/legacy`. API documentation for **@fluidframework/runtime-utils** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/service-clients/azure-client/README.md b/packages/service-clients/azure-client/README.md index fb84513fc10e..d3f149aa5036 100644 --- a/packages/service-clients/azure-client/README.md +++ b/packages/service-clients/azure-client/README.md @@ -213,6 +213,50 @@ const text1 = await map1.get("text1-unique-id").get(); API documentation for **@fluidframework/azure-client** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/service-clients/odsp-client/README.md b/packages/service-clients/odsp-client/README.md index c8a66229b425..4bd227f6edc4 100644 --- a/packages/service-clients/odsp-client/README.md +++ b/packages/service-clients/odsp-client/README.md @@ -152,6 +152,50 @@ const text1 = initialObjects.text1; API documentation for **@fluidframework/odsp-client** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/test/test-pairwise-generator/README.md b/packages/test/test-pairwise-generator/README.md index 349a6503e79a..309a8e08af05 100644 --- a/packages/test/test-pairwise-generator/README.md +++ b/packages/test/test-pairwise-generator/README.md @@ -10,6 +10,50 @@ See [examples.spec.ts](./src/test/examples.spec.ts) for usage examples. **NOTE: This package is private to the `@microsoft/fluid-framework` repository.** **It is not published, and therefore may only be used as a dev dependency.** +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/utils/odsp-doclib-utils/README.md b/packages/utils/odsp-doclib-utils/README.md index 011ebeb6264c..c8409207aa66 100644 --- a/packages/utils/odsp-doclib-utils/README.md +++ b/packages/utils/odsp-doclib-utils/README.md @@ -36,6 +36,50 @@ To access the `legacy` APIs, import via `@fluidframework/odsp-doclib-utils/legac API documentation for **@fluidframework/odsp-doclib-utils** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/utils/telemetry-utils/README.md b/packages/utils/telemetry-utils/README.md index 9da7863942b2..01fb04fbd861 100644 --- a/packages/utils/telemetry-utils/README.md +++ b/packages/utils/telemetry-utils/README.md @@ -36,6 +36,50 @@ To access the `legacy` APIs, import via `@fluidframework/telemetry-utils/legacy` API documentation for **@fluidframework/telemetry-utils** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/packages/utils/tool-utils/README.md b/packages/utils/tool-utils/README.md index 2c00fd2b1ec1..f64d3cebfdc0 100644 --- a/packages/utils/tool-utils/README.md +++ b/packages/utils/tool-utils/README.md @@ -27,6 +27,50 @@ npm i @fluidframework/tool-utils API documentation for **@fluidframework/tool-utils** is available at . +## Minimum Client Requirements + +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +### Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +### Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +### Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +### Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) + ## Contribution Guidelines There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid. diff --git a/tools/markdown-magic/README.md b/tools/markdown-magic/README.md index e69d36259249..b7eee3e5a575 100644 --- a/tools/markdown-magic/README.md +++ b/tools/markdown-magic/README.md @@ -98,6 +98,9 @@ Arguments: - `scripts`: Whether or not to include a section listing the package's `npm` scripts. - Default: `false`. - See [README_PACKAGE_SCRIPTS](#readme-package_scripts). +- `clientRequirements`: Whether or not to include a section outlining the minimum client requirements for using Fluid Framework packages. + - Default: `true`. + - See [README_CLIENT_REQUIREMENTS_SECTION](#readme_client_requirements_section). - `contributionGuidelines`: Whether or not to include a section enumerating `fluid-framework`'s contribution guidelines. - Default: `true`. - See [README_CONTRIBUTION_GUIDELINES_SECTION](#readme_contribution_guidelines_section). @@ -209,6 +212,20 @@ Arguments: Must be a positive integer. - Default: 2. +#### `README_CLIENT_REQUIREMENTS_SECTION` + +Generates a section containing minimum client requirements for using Fluid Framework packages. + +See the corresponding template [here](./src/templates/Client-Requirements-Template.md). + +Arguments: + +- `includeHeading`: Whether or not to include a section heading above the generated contents. + - Default: `true`. +- `headingLevel`: Root heading level for the generated section. + Must be a positive integer. + - Default: 2. + #### `README_TRADEMARK_SECTION` Generates a section containing our `Microsoft` trademark. diff --git a/tools/markdown-magic/src/md-magic.config.cjs b/tools/markdown-magic/src/md-magic.config.cjs index 199c4aadcbec..8235b7efd5d9 100644 --- a/tools/markdown-magic/src/md-magic.config.cjs +++ b/tools/markdown-magic/src/md-magic.config.cjs @@ -7,7 +7,6 @@ const scripts = require("markdown-magic-package-scripts"); const { defaultSectionHeadingLevel } = require("./constants.cjs"); const { - createSectionFromTemplate, formattedGeneratedContentBody, getPackageMetadata, getScopeKindFromPackage, @@ -41,11 +40,26 @@ const { * Must be a positive integer. */ const generateDependencyGuidelines = (headingOptions) => - createSectionFromTemplate("Dependency-Guidelines-Template.md", { + generateSectionFromTemplate("Dependency-Guidelines-Template.md", { ...headingOptions, headingText: "Using Fluid Framework libraries", }); +/** + * Generates a Markdown section listing Fluid Framework's minimum client requirements. + * + * @param {object} headingOptions - Heading generation options. + * @param {boolean} includeHeading - Whether or not to include a heading in the generated content. + * If not specified, no top-level heading will be included in the section. + * @param {number} headingOptions.headingLevel - Root heading level for the generated section. + * Must be a positive integer. + */ +const generateClientRequirementsSection = (headingOptions) => + generateSectionFromTemplate("Client-Requirements-Template.md", { + ...headingOptions, + headingText: "Minimum Client Requirements", + }); + /** * Generates a Markdown heading and contents with a section pointing developers to our contribution guidelines. * @@ -56,7 +70,7 @@ const generateDependencyGuidelines = (headingOptions) => * Must be a positive integer. */ const generateContributionGuidelinesSection = (headingOptions) => - createSectionFromTemplate("Contribution-Guidelines-Template.md", { + generateSectionFromTemplate("Contribution-Guidelines-Template.md", { ...headingOptions, headingText: "Contribution Guidelines", }); @@ -71,7 +85,7 @@ const generateContributionGuidelinesSection = (headingOptions) => * Must be a positive integer. */ const generateHelpSection = (headingOptions) => - createSectionFromTemplate("Help-Template.md", { + generateSectionFromTemplate("Help-Template.md", { ...headingOptions, headingText: "Help", }); @@ -86,7 +100,7 @@ const generateHelpSection = (headingOptions) => * Must be a positive integer. */ const generateTrademarkSection = (headingOptions) => - createSectionFromTemplate("Trademark-Template.md", { + generateSectionFromTemplate("Trademark-Template.md", { ...headingOptions, headingText: "Trademark", }); @@ -134,6 +148,8 @@ const generateTrademarkSection = (headingOptions) => * Default: `TRUE`. * @param {"TRUE" | "FALSE" | undefined} options.scripts - (optional) Whether or not to include a section enumerating the package.json file's dev scripts. * Default: `FALSE`. + * @param {"TRUE" | "FALSE" | undefined} options.clientRequirements - (optional) Whether or not to include a section listing Fluid Framework's minimum client requirements. + * Default: `TRUE`. * @param {"TRUE" | "FALSE" | undefined} options.contributionGuidelines - (optional) Whether or not to include a section outlining fluid-framework's contribution guidelines. * Default: `TRUE`. * @param {"TRUE" | "FALSE" | undefined} options.help - (optional) Whether or not to include a developer help section. @@ -192,6 +208,10 @@ function libraryPackageReadmeTransform(content, options, config) { sections.push(generatePackageScriptsSection(scriptsTable, sectionHeadingOptions)); } + if (options.contributionGuidelines !== "FALSE") { + sections.push(generateClientRequirementsSection(sectionHeadingOptions)); + } + if (options.contributionGuidelines !== "FALSE") { sections.push(generateContributionGuidelinesSection(sectionHeadingOptions)); } @@ -397,6 +417,33 @@ module.exports = { */ README_IMPORT_INSTRUCTIONS: packageImportInstructionsSectionTransform, + /** + * Generates a README section with Fluid Framework client requirements. + * + * @param {object} content - The original document file contents. + * @param {object} options - Transform options. + * @param {"TRUE" | "FALSE" | undefined} includeHeading - (optional) Whether or not to include a top-level heading in the generated section. + * default: `TRUE`. + * @param {number | undefined} options.headingLevel - (optional) Heading level for the section. + * Must be a positive integer. + * Default: {@link defaultSectionHeadingLevel}. + * @param {object} config - Transform configuration. + * @param {string} config.originalPath - Path to the document being modified. + * + * @example + * + * ```markdown + * + * + * ``` + */ + README_CLIENT_REQUIREMENTS_SECTION: (content, options, config) => { + return templateTransform( + "Client-Requirements-Template.md", + parseHeadingOptions(options, "Client Requirements"), + ); + }, + /** * Generates a README section with Microsoft trademark info. * diff --git a/tools/markdown-magic/src/templates/Client-Requirements-Template.md b/tools/markdown-magic/src/templates/Client-Requirements-Template.md new file mode 100644 index 000000000000..c4869a82a202 --- /dev/null +++ b/tools/markdown-magic/src/templates/Client-Requirements-Template.md @@ -0,0 +1,41 @@ +These are the platform requirements for the current version of Fluid Framework Client Packages. +These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter. +For Long Term Support (LTS) versions this can require supporting these platforms for several years. + +It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug. +If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request. +When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working. + +# Supported Runtimes + +- NodeJs ^20.10.0 except that we will drop support for it [when NodeJs 20 loses its upstream support on 2026-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS (22) at least 1 year before 20 is end-of-life. This same policy applies to NodeJS 22 when it is end of life (2027-04-30). +- Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards). + +# Supported Tools + +- TypeScript 5.4: + - All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported. + - [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required. + - [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported. + - `exactOptionalPropertyTypes` is currently not fully supported. + If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases. +- [webpack](https://webpack.js.org/) 5 + - We are not intending to be prescriptive about what bundler to use. + Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test. + +# Module Resolution + +[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm). +Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development. + +# Module Formats + +- ES Modules: + ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported. +- CommonJs: + Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below. + This is done to accommodate some workflows without good ES Module support. + If you have a workflow you would like included in this list, file an issue. + Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here. + + - Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648)) diff --git a/tools/markdown-magic/src/templates/README.md b/tools/markdown-magic/src/templates/README.md index d03949cc12f8..9b090fe91c56 100644 --- a/tools/markdown-magic/src/templates/README.md +++ b/tools/markdown-magic/src/templates/README.md @@ -1,3 +1,15 @@ +# Templates + This directory contains templates used for content generation. NOTE: changes to these contents constitute a breaking change, since it will change the contents generated in consumers' documents. + +## Formatting + +Some of the content logic makes assumptions about the formatting of the template contents in this directory. +Namely, it assumes: + +- Documents do not contain a top-level heading. + - Used to allow dynamic generation of top-level headings for embedded sections. +- Any sub-headings are encoded as level 1 headings (e.g., "# Foo", not "## Foo"). + - Used to dynamically adjust heading levels to conform to the target documents needs. diff --git a/tools/markdown-magic/src/transforms/generateSectionFromTemplate.cjs b/tools/markdown-magic/src/transforms/generateSectionFromTemplate.cjs index 3af04093c538..b6ffd99074f4 100644 --- a/tools/markdown-magic/src/transforms/generateSectionFromTemplate.cjs +++ b/tools/markdown-magic/src/transforms/generateSectionFromTemplate.cjs @@ -17,7 +17,10 @@ const { formattedSectionText, readTemplate } = require("../utilities.cjs"); * A heading will only be included if this is specified. */ const generateSectionFromTemplate = (templateFileName, headingOptions) => { - const sectionBody = readTemplate(templateFileName); + const sectionBody = readTemplate( + templateFileName, + headingOptions?.headingLevel ?? 0, + ); return formattedSectionText(sectionBody, headingOptions); }; diff --git a/tools/markdown-magic/src/utilities.cjs b/tools/markdown-magic/src/utilities.cjs index 2649b267e7dc..334ab2057f9d 100644 --- a/tools/markdown-magic/src/utilities.cjs +++ b/tools/markdown-magic/src/utilities.cjs @@ -18,28 +18,28 @@ const { * Reads and returns the contents from the specified template file. * * @param {string} templateFileName - Name of the file to read, under {@link templatesDirectoryPath} (e.g. "Trademark-Template.md"). + * @param {number} headingOffset - (optional) Level offset for all headings in the target template. + * Must be a non-negative integer. */ -const readTemplate = (templateFileName) => { - return fs +const readTemplate = (templateFileName, headingOffset = 0) => { + if (!Number.isInteger(headingOffset) || headingOffset < 0) { + throw new TypeError( + `"headingOffset" must be a non-negative integer. Got "${headingOffset}".`, + ); + } + + const unmodifiedContents = fs .readFileSync(path.resolve(templatesDirectoryPath, templateFileName), { encoding: "utf-8", }) .trim(); -}; -/** - * Generates a simple block of Markdown contents by embedding the specified template and (optionally) including a header. - * - * @param {string} templateName - The name of the template file to embed. - * @param {object} headingOptions - (optional) Heading generation options. - * @param {boolean} headingOptions.includeHeading - Whether or not to include a top-level heading in the generated section. - * @param {number} headingOptions.headingLevel - Root heading level for the generated section. - * Must be a positive integer. - * @param {string} headingOptions.headingText - Text to display in the section heading, if one was requested. - */ -const createSectionFromTemplate = (templateName, headingOptions) => { - const sectionBody = readTemplate(templateName); - return formattedSectionText(sectionBody, headingOptions); + if (headingOffset === 0) { + return unmodifiedContents; + } + + const headingOffsetString = "#".repeat(headingOffset); + return unmodifiedContents.replace(/(^#)/gm, `$1${headingOffsetString}`); }; /** @@ -198,7 +198,6 @@ function parseHeadingOptions(transformationOptions, headingText) { } module.exports = { - createSectionFromTemplate, formattedSectionText, formattedGeneratedContentBody, formattedEmbeddedContentBody, diff --git a/tools/markdown-magic/test/library-package-readme.md b/tools/markdown-magic/test/library-package-readme.md index dd809a7e9e8c..49d4a7e07d46 100644 --- a/tools/markdown-magic/test/library-package-readme.md +++ b/tools/markdown-magic/test/library-package-readme.md @@ -46,6 +46,50 @@ API documentation for **@test/test-package** is available at