diff --git a/docs/browserslist/configure-project.md b/docs/browserslist/configure-project.md index 5b19c9fa..bfc04e7b 100644 --- a/docs/browserslist/configure-project.md +++ b/docs/browserslist/configure-project.md @@ -58,7 +58,7 @@ Refer to the [Browserslist documentation](https://github.com/browserslist/browse ## 4. Try it :rocket: -To test your new [Browserslist](https://browsersl.ist/) configuration, open a terminal at the root of the project and execute the following command: +To test your new Browserslist configuration, open a terminal at the root of the project and execute the following command: +++ pnpm ```bash diff --git a/docs/default.md b/docs/default.md index 1e51f07f..2e6b7b81 100644 --- a/docs/default.md +++ b/docs/default.md @@ -31,7 +31,7 @@ npm create @workleap/project@latest Starting a new web application is still an arduous task. There are so many tools to choose from, learn, install and configure, it can be daunting. -For an organization like [Workleap](https://workleap.com/), with a large suite of products, it **doesn't make sense to start over every time** we invest in a new idea or add a new vertical to an existing product. Developers working on a new project shouldn't spend their first day's figuring out which [ESLint](https://eslint.org/) rules to enable/disable, or how to transpile their [React](https://react.dev/) code, they should rather **focus on writing features code**. +For an organization like Workleap, with a large suite of products, it **doesn't make sense to start over every time** we invest in a new idea or add a new vertical to an existing product. Developers working on a new project shouldn't spend their first day's figuring out which ESLint rules to enable/disable, or how to transpile their React code, they should rather **focus on writing features code**. ### Filling the gap diff --git a/docs/eslint/advanced-composition.md b/docs/eslint/advanced-composition.md index 1deaed55..d8173195 100644 --- a/docs/eslint/advanced-composition.md +++ b/docs/eslint/advanced-composition.md @@ -16,7 +16,7 @@ If the default [by project type configurations](default.md/#available-configurat | :icon-mark-github: [typescript](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/typescript.ts) | Rules for [TypeScript](https://www.typescriptlang.org/) files. | | :icon-mark-github: [react](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/react.ts) | Rules for [React](https://react.dev/) files. | | :icon-mark-github: [jest](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/jest.ts) | Rules for [Jest](https://jestjs.io/) files. | -| :icon-mark-github: [testing-library](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/testing-library.ts) | Rules for Jest files using [testing-library](https://testing-library.com/). | +| :icon-mark-github: [testing-library](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/testing-library.ts) | Rules for Jest files using [Testing Library](https://testing-library.com/). | | :icon-mark-github: [storybook](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/storybook.ts) | Rules for [Storybook](https://storybook.js.org/) story files. | | :icon-mark-github: [mdx](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/mdx.ts) | Rules for [MDX](https://mdxjs.com/) files (used for Storybook MDX stories). | diff --git a/docs/eslint/default.md b/docs/eslint/default.md index 914703fa..67268801 100644 --- a/docs/eslint/default.md +++ b/docs/eslint/default.md @@ -54,14 +54,14 @@ This way, it's pretty straightforward for the consumer to configure ESLint as it | Name | Description | | --- | --- | -| :icon-mark-github: [web-application](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/by-project-type/web-application.ts) | For web applications developed with [React](https://react.dev/) and [TypeScript](https://www.typescriptlang.org/). | -| :icon-mark-github: [react-library](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/by-project-type/react-library.ts) | For TypeScript libraries developed **with** [React](https://react.dev/). | -| :icon-mark-github: [typescript-library](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/by-project-type/typescript-library.ts) | For TypeScript libraries developed **without** [React](https://react.dev/). | +| :icon-mark-github: [web-application](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/by-project-type/web-application.ts) | For web applications developed with React and TypeScript. | +| :icon-mark-github: [react-library](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/by-project-type/react-library.ts) | For TypeScript libraries developed **with** React. | +| :icon-mark-github: [typescript-library](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/by-project-type/typescript-library.ts) | For TypeScript libraries developed **without** React. | | :icon-mark-github: [monorepo-workspace](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/eslint-plugin/lib/config/by-project-type/monorepo-workspace.ts) | For the workspace configuration of a monorepo solution. | ## Prettier -For a complete explanation of why we chose to stick with [ESLint](https://eslint.org/) for stylistic rules rather than migrating to [Prettier](https://prettier.io/), read the following [article](https://antfu.me/posts/why-not-prettier). +For a complete explanation of why we chose to stick with ESLint for stylistic rules rather than migrating to Prettier, read the following [article](https://antfu.me/posts/why-not-prettier). ## Getting started diff --git a/docs/eslint/integrate-vscode.md b/docs/eslint/integrate-vscode.md index 36bacfed..1fa1a357 100644 --- a/docs/eslint/integrate-vscode.md +++ b/docs/eslint/integrate-vscode.md @@ -11,7 +11,7 @@ meta: ## 1. Install the ESLint extension -Open [VS Code](https://code.visualstudio.com/) and install the [dbaeumer.vscode-eslint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) extension. +Open VS Code and install the [dbaeumer.vscode-eslint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) extension. ## 2. Configure VS Code diff --git a/docs/eslint/setup-monorepo.md b/docs/eslint/setup-monorepo.md index 3f839947..dcca3c3a 100644 --- a/docs/eslint/setup-monorepo.md +++ b/docs/eslint/setup-monorepo.md @@ -58,7 +58,7 @@ Then, open the newly created file and extend the default configuration with the ## 3. Ignore files -[ESLint](https://eslint.org/) can be configured to [ignore](https://eslint.org/docs/latest/use/configure/ignore) certain files and directories while linting by specifying one or more glob patterns. +ESLint can be configured to [ignore](https://eslint.org/docs/latest/use/configure/ignore) certain files and directories while linting by specifying one or more glob patterns. To do so, first, create a `.eslintignore` file at the root of the solution workspace: @@ -86,7 +86,7 @@ node_modules ## 4. Configure indent style -[ESLint](https://eslint.org/) offers [built-in rules](https://eslint.org/docs/latest/rules/indent) for configuring the indentation style of a codebase. However, there's a catch: when [VS Code auto-formatting](https://code.visualstudio.com/docs/editor/codebasics#_formatting) feature is enabled, it might conflict with the configured indentation rules if they are set differently. +ESLint offers [built-in rules](https://eslint.org/docs/latest/rules/indent) for configuring the indentation style of a codebase. However, there's a catch: when [VS Code auto-formatting](https://code.visualstudio.com/docs/editor/codebasics#_formatting) feature is enabled, it might conflict with the configured indentation rules if they are set differently. To guarantee a consistent indentation, we recommend using [EditorConfig](https://editorconfig.org/) on the consumer side. With EditorConfig, the indent style can be configured in a single file and be applied consistently across various formatting tools, including ESlint and [VS Code](https://code.visualstudio.com/). @@ -187,7 +187,7 @@ Then, open the newly created file and extend the default configuration with one ### web-application -For an application developed with [TypeScript](https://www.typescriptlang.org/) and [React](https://react.dev/), use the following configuration: +For an application developed with TypeScript and React, use the following configuration: ```json !#4 packages/app/.eslintrc.json { @@ -199,7 +199,7 @@ For an application developed with [TypeScript](https://www.typescriptlang.org/) ### react-library -For a [TypeScript](https://www.typescriptlang.org/) library developed **with** [React](https://react.dev/), use the following configuration: +For a TypeScript library developed **with** React, use the following configuration: ```json !#4 packages/app/.eslintrc.json { @@ -211,7 +211,7 @@ For a [TypeScript](https://www.typescriptlang.org/) library developed **with** [ ### typescript-library -For a [TypeScript](https://www.typescriptlang.org/) library developed **without** [React](https://react.dev/), use the following configuration: +For a TypeScript library developed **without** React, use the following configuration: ```json !#4 packages/app/.eslintrc.json { @@ -231,7 +231,7 @@ New projects shouldn't have to customize the default configurations offered by ` ## 10. Try it :rocket: -To test your new [ESLint](https://eslint.org/) setup, open a JavaScript file, type invalid code (e.g. `var x = 0;`), then save. Open a terminal at the root of the solution and execute the [CLI script added earlier](#5-add-a-cli-script): +To test your new ESLint setup, open a JavaScript file, type invalid code (e.g. `var x = 0;`), then save. Open a terminal at the root of the solution and execute the [CLI script added earlier](#5-add-a-cli-script): +++ pnpm ```bash diff --git a/docs/eslint/setup-polyrepo.md b/docs/eslint/setup-polyrepo.md index d633c0e7..348a800f 100644 --- a/docs/eslint/setup-polyrepo.md +++ b/docs/eslint/setup-polyrepo.md @@ -43,7 +43,7 @@ Then, open the newly created file and extend the default configuration with one ### web-application -For an application developed with [TypeScript](https://www.typescriptlang.org/) and [React](https://react.dev/), use the following configuration: +For an application developed with TypeScript and React, use the following configuration: ```json !#4 .eslintrc.json { @@ -55,7 +55,7 @@ For an application developed with [TypeScript](https://www.typescriptlang.org/) ### react-library -For a [TypeScript](https://www.typescriptlang.org/) library developed **with** [React](https://react.dev/), use the following configuration: +For a TypeScript library developed **with** React, use the following configuration: ```json !#4 .eslintrc.json { @@ -67,7 +67,7 @@ For a [TypeScript](https://www.typescriptlang.org/) library developed **with** [ ### typescript-library -For a [TypeScript](https://www.typescriptlang.org/) library developed **without** [React](https://react.dev/), use the following configuration: +For a TypeScript library developed **without** React, use the following configuration: ```json !#4 .eslintrc.json { @@ -79,7 +79,7 @@ For a [TypeScript](https://www.typescriptlang.org/) library developed **without* ## 3. Ignore files -[ESLint](https://eslint.org/) can be configured to [ignore](https://eslint.org/docs/latest/use/configure/ignore) certain files and directories while linting by specifying one or more glob patterns. +ESLint can be configured to [ignore](https://eslint.org/docs/latest/use/configure/ignore) certain files and directories while linting by specifying one or more glob patterns. To do so, first, create an `.eslintignore` file at the root of the solution: @@ -157,7 +157,7 @@ New projects shouldn't have to customize the default configurations offered by ` ## 7. Try it :rocket: -To test your new [ESLint](https://eslint.org/) setup, open a JavaScript file, type invalid code (e.g. `var x = 0;`), then save. Open a terminal at the root of the solution and execute the [CLI script added earlier](#5-add-a-cli-script): +To test your new ESLint setup, open a JavaScript file, type invalid code (e.g. `var x = 0;`), then save. Open a terminal at the root of the solution and execute the [CLI script added earlier](#5-add-a-cli-script): +++ pnpm ```bash diff --git a/docs/postcss/configure-project.md b/docs/postcss/configure-project.md index 8aae652d..e022d25c 100644 --- a/docs/postcss/configure-project.md +++ b/docs/postcss/configure-project.md @@ -38,7 +38,7 @@ project ├── postcss.config.ts ``` -Then, open the newly created file and `export` the [PostCSS](https://postcss.org/) configuration by using the `defineConfig(options)` function: +Then, open the newly created file and `export` the PostCSS configuration by using the `defineConfig(options)` function: ```ts !#3 postcss.config.ts import { defineConfig } from "@workleap/postcss-configs"; @@ -155,7 +155,7 @@ export default defineConfig({ ## 5. Configure webpack -To integrate with [webpack](https://webpack.js.org/), update your configuration file to include a [postcss-loader](https://www.npmjs.com/package/postcss-loader): +To integrate with webpack, update your configuration file to include a [postcss-loader](https://www.npmjs.com/package/postcss-loader): ```js !#12 webpack.config.js // @ts-check @@ -179,7 +179,7 @@ export default { ## 6. Try it :rocket: -To test your new [PostCSS](https://postcss.org/) configuration, create and import a CSS file with the following code: +To test your new PostCSS configuration, create and import a CSS file with the following code: ```css example.css .example { @@ -214,7 +214,7 @@ Then, process the file with `postcss-cli` by executing the following command in npx postcss example.css -o out.css ``` -Whether you processed the CSS with webpack or `postcss-cli`, most of the CSS properties in the `.example` CSS class should have been prefixed (it can vary based on your [Browserslist](https://browsersl.ist/) configuration): +Whether you processed the CSS with webpack or `postcss-cli`, most of the CSS properties in the `.example` CSS class should have been prefixed (it can vary based on your Browserslist configuration): ```css out.css .example { diff --git a/docs/postcss/default.md b/docs/postcss/default.md index e0b2f837..8a045d29 100644 --- a/docs/postcss/default.md +++ b/docs/postcss/default.md @@ -32,7 +32,7 @@ As we actively work on improving our build time and **minimize** the number of t Here's a couple of ideas to move away from PostCSS: -- Prefer native CSS to [SCSS](https://sass-lang.com/documentation/syntax/). +- Prefer native CSS to SCSS. - Avoid CSS nesting, it usually makes code harder to read anyway. If you really need nesting, [native support](https://www.w3.org/TR/css-nesting-1/) is coming soon. - Force developers to use `rem` by disabling the use of `px` with [Stylelint](https://stylelint.io/). - Prefix CSS properties directly in the codebase rather than relying on [Autoprefixer](https://github.com/postcss/autoprefixer). As browser vendors are now [putting experimental features behind a flag](https://github.com/postcss/autoprefixer) rather than using prefixes, there aren't many CSS properties still requiring a prefix. diff --git a/docs/stylelint/default.md b/docs/stylelint/default.md index 77d36fd3..16c0e91c 100644 --- a/docs/stylelint/default.md +++ b/docs/stylelint/default.md @@ -26,9 +26,9 @@ npm create @workleap/project@latest +++ !!! -## Sass +## SCSS -While [Sass](https://sass-lang.com/) still offers numerous advantages, as we actively work on improving our build time and **minimize** the number of tools **compiling/transpiling** frontend code, we choose to move away from Sass and not provide any Stylelint's rules for Sass. If you are still using Sass strictly for nesting, note that [native support for nesting](https://www.w3.org/TR/css-nesting-1/) is coming soon to CSS. +While SCSS still offers numerous advantages, as we actively work on improving our build time and **minimize** the number of tools **compiling/transpiling** frontend code, we choose to move away from Sass and not provide any Stylelint's rules for Sass. If you are still using Sass strictly for nesting, note that [native support for nesting](https://www.w3.org/TR/css-nesting-1/) is coming soon to CSS. ## Prettier @@ -43,7 +43,7 @@ Since we choose to [stick with ESLint for JavaScript and JSON stylistic rules](. !**/*.css ``` -Otherwise, Prettier will also format your `.js,.json,.ts` files and you'll end up with conflicts between Prettier and [ESLint](https://eslint.org/). +Otherwise, Prettier will also format your `.js,.json,.ts` files and you'll end up with conflicts between [Prettier](https://prettier.io/) and [ESLint](https://eslint.org/). ## Getting started diff --git a/docs/stylelint/integrate-vscode.md b/docs/stylelint/integrate-vscode.md index 00edc9b7..a28fc8a1 100644 --- a/docs/stylelint/integrate-vscode.md +++ b/docs/stylelint/integrate-vscode.md @@ -11,7 +11,7 @@ meta: ## 1. Install the Stylelint extension -Open [VS Code](https://code.visualstudio.com/) and install the [stylelint.vscode-stylelint](https://marketplace.visualstudio.com/items?stylelint.vscode-stylelint.vscode-eslint) extension. +Open VS Code and install the [stylelint.vscode-stylelint](https://marketplace.visualstudio.com/items?stylelint.vscode-stylelint.vscode-eslint) extension. ## 2. Configure VS Code diff --git a/docs/stylelint/setup-monorepo.md b/docs/stylelint/setup-monorepo.md index f56df04a..53a23fe6 100644 --- a/docs/stylelint/setup-monorepo.md +++ b/docs/stylelint/setup-monorepo.md @@ -57,7 +57,7 @@ Then, open the newly created file and extend the default configuration with the ## 3. Ignore files -[Stylelint](https://stylelint.io/) can be configured to [ignore](https://stylelint.io/user-guide/ignore-code#files-entirely) certain files and directories while linting by specifying one or more glob patterns. +Stylelint can be configured to [ignore](https://stylelint.io/user-guide/ignore-code#files-entirely) certain files and directories while linting by specifying one or more glob patterns. To do so, first, create an `.stylelintignore` file at the root of the solution workspace: @@ -108,9 +108,9 @@ Then, open the newly created file and paste the following ignore rules: ## 5. Configure indent style -[Prettier](https://prettier.io/) offers [built-in rules](https://prettier.io/docs/en/options#tab-width) for configuring the indentation style of a codebase. However, there's a catch: when [VS Code auto-formatting](https://code.visualstudio.com/docs/editor/codebasics#_formatting) feature is enabled, it might conflict with the configured indentation rules if they are set differently. +Prettier offers [built-in rules](https://prettier.io/docs/en/options#tab-width) for configuring the indentation style of a codebase. However, there's a catch: when [VS Code auto-formatting](https://code.visualstudio.com/docs/editor/codebasics#_formatting) feature is enabled, it might conflict with the configured indentation rules if they are set differently. -To guarantee a consistent indentation, we recommend using [EditorConfig](https://editorconfig.org/) on the consumer side. With EditorConfig, the indent style can be configured in a single file and be applied consistently across various formatting tools, including ESlint and [VS Code](https://code.visualstudio.com/). +To guarantee a consistent indentation, we recommend using [EditorConfig](https://editorconfig.org/) on the consumer side. With EditorConfig, the indent style can be configured in a single file and be applied consistently across various formatting tools, including ESlint and VS Code. First, create a `.editorconfig` file at the root of the solution workspace: diff --git a/docs/stylelint/setup-polyrepo.md b/docs/stylelint/setup-polyrepo.md index 579a3223..59ea8d26 100644 --- a/docs/stylelint/setup-polyrepo.md +++ b/docs/stylelint/setup-polyrepo.md @@ -50,7 +50,7 @@ Then, open the newly created file and extend the default configuration with the ## 3. Ignore files -[Stylelint](https://stylelint.io/) can be configured to [ignore](https://stylelint.io/user-guide/ignore-code#files-entirely) certain files and directories while linting by specifying one or more glob patterns. +Stylelint can be configured to [ignore](https://stylelint.io/user-guide/ignore-code#files-entirely) certain files and directories while linting by specifying one or more glob patterns. To do so, first, create a `.stylelintignore` file at the root of the solution: @@ -95,9 +95,9 @@ Then, open the newly created file and paste the following ignore rules: ## 5. Configure indent style -[Prettier](https://prettier.io/) offers [built-in rules](https://prettier.io/docs/en/options#tab-width) for configuring the indentation style of a codebase. However, there's a catch: when [VS Code auto-formatting](https://code.visualstudio.com/docs/editor/codebasics#_formatting) feature is enabled, it might conflict with the configured indentation rules if they are set differently. +Prettier offers [built-in rules](https://prettier.io/docs/en/options#tab-width) for configuring the indentation style of a codebase. However, there's a catch: when [VS Code auto-formatting](https://code.visualstudio.com/docs/editor/codebasics#_formatting) feature is enabled, it might conflict with the configured indentation rules if they are set differently. -To guarantees a consistent indentation, we recommend using [EditorConfig](https://editorconfig.org/) on the consumer side. With EditorConfig, the indent style can be configured in a single file and be applied consistently across various formatting tools, including Prettier and [VS Code](https://code.visualstudio.com/). +To guarantees a consistent indentation, we recommend using [EditorConfig](https://editorconfig.org/) on the consumer side. With EditorConfig, the indent style can be configured in a single file and be applied consistently across various formatting tools, including Prettier and VS Code. First, create a `.editorconfig` file at the root of the solution: diff --git a/docs/swc/configure-build.md b/docs/swc/configure-build.md index cce9ac85..957fc5c5 100644 --- a/docs/swc/configure-build.md +++ b/docs/swc/configure-build.md @@ -39,7 +39,7 @@ web-project ├── swc.build.js ``` -Then, open the newly created file and export the [SWC](https://swc.rs/) configuration by using the `defineBuildConfig(targets, options)` function: +Then, open the newly created file and export the SWC configuration by using the `defineBuildConfig(targets, options)` function: ```js !#5,7 swc.build.js // @ts-check @@ -55,7 +55,7 @@ export default defineBuildConfig(targets); In the previous code sample, the `defineBuildConfig(targets, options)` function receives a list of **minimal browser versions to support** through the `targets` parameter. -The expected behavior for the supported browsers would be for [SWC](https://swc.rs/) to automatically load the minimal browser versions from the closest `.browserslistrc` [configuration file](https://github.com/browserslist/browserslist#browserslistrc). However, there is currently an [issue](https://github.com/swc-project/swc/issues/3365) preventing SWC from doing so when the configuration file include a query referencing an external [Browserslist](https://browsersl.ist/) configuration: +The expected behavior for the supported browsers would be for SWC to automatically load the minimal browser versions from the closest `.browserslistrc` [configuration file](https://github.com/browserslist/browserslist#browserslistrc). However, there is currently an [issue](https://github.com/swc-project/swc/issues/3365) preventing SWC from doing so when the configuration file include a query referencing an external [Browserslist](https://browsersl.ist/) configuration: ```.browserslistrc extends @workleap/browserslist-config @@ -65,7 +65,7 @@ Therefore, `@workleap/swc-configs` has chosen to **delegate** the loading of the ### `browserslistToSwc` -To help consumers provide SWC [targets](https://swc.rs/docs/configuration/supported-browsers#targets) from a [Browserslist](https://browsersl.ist/) configuration, `@workleap/swc-configs` offers the `browserslistToSwc(options)` utility function. +To help consumers provide SWC [targets](https://swc.rs/docs/configuration/supported-browsers#targets) from a Browserslist configuration, `@workleap/swc-configs` offers the `browserslistToSwc(options)` utility function. This function can either transform an array of Browserslist [queries](https://github.com/browserslist/browserslist#queries) to SWC targets: @@ -108,7 +108,7 @@ The `defineBuildConfig(targets, options)` function can be used as shown in the p - **Type**: `"ecmascript" | "typescript"` - **Default**: `"typescript"` -Whether SWC should expect to parse JavaScript or [TypeScript](https://www.typescriptlang.org/) code. +Whether SWC should expect to parse JavaScript or TypeScript code. ```js !#8 swc.build.js // @ts-check @@ -179,7 +179,7 @@ export const transformer: SwcConfigTransformer = (config: SwcConfig, context: Sw ## 5. Configure webpack -To integrate with [webpack](https://webpack.js.org/), update your configuration file to include an [swc-loader](https://swc.rs/docs/usage/swc-loader): +To integrate with webpack, update your configuration file to include an [swc-loader](https://swc.rs/docs/usage/swc-loader): ```js !#10 webpack.config.js // @ts-check diff --git a/docs/swc/configure-dev.md b/docs/swc/configure-dev.md index 401e4da1..8f9a0192 100644 --- a/docs/swc/configure-dev.md +++ b/docs/swc/configure-dev.md @@ -39,7 +39,7 @@ web-project ├── swc.dev.js ``` -Then, open the newly created file and export the [SWC](https://swc.rs/) configuration by using the `defineDevConfig(targets, options)` function: +Then, open the newly created file and export the SWC configuration by using the `defineDevConfig(targets, options)` function: ```js !#5,7 swc.dev.js // @ts-check @@ -55,7 +55,7 @@ export default defineDevConfig(targets); In the previous code sample, the `defineDevConfig(targets, options)` function receives a list of **minimal browser versions to support** through the `targets` parameter. -The expected behavior for the supported browsers would be for [SWC](https://swc.rs/) to automatically load the minimal browser versions from the closest `.browserslistrc` [configuration file](https://github.com/browserslist/browserslist#browserslistrc). However, there is currently an [issue](https://github.com/swc-project/swc/issues/3365) preventing SWC from doing so when the configuration file include a query referencing an external [Browserslist](https://browsersl.ist/) configuration: +The expected behavior for the supported browsers would be for SWC to automatically load the minimal browser versions from the closest `.browserslistrc` [configuration file](https://github.com/browserslist/browserslist#browserslistrc). However, there is currently an [issue](https://github.com/swc-project/swc/issues/3365) preventing SWC from doing so when the configuration file include a query referencing an external [Browserslist](https://browsersl.ist/) configuration: ```.browserslistrc extends @workleap/browserslist-config @@ -65,7 +65,7 @@ Therefore, `@workleap/swc-configs` has chosen to **delegate** the loading of the ### `browserslistToSwc` -To help consumers provide SWC [targets](https://swc.rs/docs/configuration/supported-browsers#targets) from a [Browserslist](https://browsersl.ist/) configuration, `@workleap/swc-configs` offers the `browserslistToSwc(options)` utility function. +To help consumers provide SWC [targets](https://swc.rs/docs/configuration/supported-browsers#targets) from a Browserslist configuration, `@workleap/swc-configs` offers the `browserslistToSwc(options)` utility function. This function can either transform an array of Browserslist [queries](https://github.com/browserslist/browserslist#queries) to SWC targets: @@ -127,7 +127,7 @@ export default defineDevConfig(targets, { - **Type**: `"ecmascript" | "typescript"` - **Default**: `"typescript"` -Whether SWC should expect to parse JavaScript or [TypeScript](https://www.typescriptlang.org/) code. +Whether SWC should expect to parse JavaScript or TypeScript code. ```js !#8 swc.dev.js // @ts-check @@ -198,7 +198,7 @@ export const transformer: SwcConfigTransformer = (config: SwcConfig, context: Sw ## 5. Configure webpack -To integrate with [webpack](https://webpack.js.org/), update your configuration file to include an [swc-loader](https://swc.rs/docs/usage/swc-loader): +To integrate with webpack, update your configuration file to include an [swc-loader](https://swc.rs/docs/usage/swc-loader): ```js !#10 webpack.config.js // @ts-check @@ -224,7 +224,7 @@ export default { ## 6. Try it :rocket: -To test your new [SWC](https://swc.rs/) configuration, create a Typescript file with the following code: +To test your new SWC configuration, create a Typescript file with the following code: ```ts say.ts export function say(string: value) { diff --git a/docs/swc/configure-jest.md b/docs/swc/configure-jest.md index bd326b44..55e076ab 100644 --- a/docs/swc/configure-jest.md +++ b/docs/swc/configure-jest.md @@ -30,7 +30,7 @@ npm install -D @workleap/swc-configs @swc/jest @swc/core @swc/helpers ## 2. Configure SWC !!!info -To use a [TypeScript](https://www.typescriptlang.org/) configuration file, make sure that your Jest configuration is also in TypeScript. +To use a TypeScript configuration file, make sure that your Jest configuration is also in TypeScript. !!! First, create a configuration file named `swc.jest.ts` at the root of the project: @@ -44,7 +44,7 @@ web-project ├── jest.config.ts ``` -Then, open the newly created file and export the [SWC](https://swc.rs/) configuration by using the `defineJestConfig(options)` function: +Then, open the newly created file and export the SWC configuration by using the `defineJestConfig(options)` function: ```ts !#6-8 swc.jest.ts import { defineJestConfig } from "@workleap/swc-configs"; @@ -61,7 +61,7 @@ The `defineJestConfig(options)` function can be used as shown in the previous ex - **Type**: `boolean` - **Default**: `false` -Whether or not to transform [React](https://react.dev/) code. +Whether or not to transform React code. ```ts !#4 swc.jest.ts import { defineJestConfig } from "@workleap/swc-configs"; @@ -76,7 +76,7 @@ export default defineJestConfig({ - **Type**: `"ecmascript" | "typescript"` - **Default**: `"typescript"` -Whether SWC should expect to parse JavaScript or [TypeScript](https://www.typescriptlang.org/) code. +Whether SWC should expect to parse JavaScript or TypeScript code. ```ts !#4 swc.jest.ts import { defineJestConfig } from "@workleap/swc-configs"; @@ -121,7 +121,7 @@ export default defineJestConfig({ ## 5. Configure Jest -To configure [Jest](https://jestjs.io/), open the project `jest.config.ts` file and add the following code: +To configure Jest, open the project `jest.config.ts` file and add the following code: ```ts !#4-6 jest.config.ts import { swcConfig } from "./swc.jest.ts"; @@ -135,7 +135,7 @@ const config = { ## 6. Try it :rocket: -To test your new [SWC](https://swc.rs/) configuration, create a Jest test in Typescript: +To test your new SWC configuration, create a Jest test in Typescript: ```ts appendWorld.test.ts export function appendWorld(string: value) { diff --git a/docs/swc/default.md b/docs/swc/default.md index 1d666883..61489cda 100644 --- a/docs/swc/default.md +++ b/docs/swc/default.md @@ -28,7 +28,7 @@ npm create @workleap/project@latest ## A word about Rspack -Somewhere in 2024, [we expect to migrate from webpack to Rspack](../webpack/default.md#a-word-about-rspack). Once the migration is completed, the SWC [development](configure-dev.md) and [production](configure-build.md) configurations will not be used anymore as [Rspack](https://www.rspack.dev/) offers out of the box support for [React](https://react.dev/) and [TypeScript](https://www.typescriptlang.org/). +Somewhere in 2024, [we expect to migrate from webpack to Rspack](../webpack/default.md#a-word-about-rspack). Once the migration is completed, the SWC [development](configure-dev.md) and [production](configure-build.md) configurations will not be used anymore as [Rspack](https://www.rspack.dev/) offers out of the box support for React and TypeScript. Meanwhile, you can **confidently start a new project with these SWC configurations** as the migration process to Rspack is expected to be seamless. diff --git a/docs/tsup/configure-build.md b/docs/tsup/configure-build.md index 288aefbc..df8eb02a 100644 --- a/docs/tsup/configure-build.md +++ b/docs/tsup/configure-build.md @@ -39,7 +39,7 @@ web-project ├── tsup.build.ts ``` -Then, open the newly created file and export the [tsup](https://tsup.egoist.dev/) configuration by using the `defineBuildConfig(options)` function: +Then, open the newly created file and export the tsup configuration by using the `defineBuildConfig(options)` function: ```ts tsup.build.ts import { defineBuildConfig } from "@workleap/tsup-configs"; @@ -129,4 +129,4 @@ To build the bundle files for production, add the following script to your proje ## 6. Try it :rocket: -To test your new [tsup](https://tsup.egoist.dev/) configuration, open a terminal at the root of the project and execute the [CLI script added previously](#5-add-a-cli-script). The build process should complete without outputting any error in the terminal and the bundle files should be available in the `/dist` folder (or any other `outputDir` you configured). +To test your new tsup configuration, open a terminal at the root of the project and execute the [CLI script added previously](#5-add-a-cli-script). The build process should complete without outputting any error in the terminal and the bundle files should be available in the `/dist` folder (or any other `outputDir` you configured). diff --git a/docs/tsup/configure-dev.md b/docs/tsup/configure-dev.md index 4117e71a..fdd609d0 100644 --- a/docs/tsup/configure-dev.md +++ b/docs/tsup/configure-dev.md @@ -39,7 +39,7 @@ web-project ├── tsup.dev.ts ``` -Then, open the newly created file and export the [tsup](https://tsup.egoist.dev/) configuration by using the `defineDevConfig(options)` function: +Then, open the newly created file and export the tsup configuration by using the `defineDevConfig(options)` function: ```ts tsup.dev.ts import { defineDevConfig } from "@workleap/tsup-configs"; @@ -129,4 +129,4 @@ To initiate the development process, add the following script to your project `p ## 6. Try it :rocket: -To test your new [tsup](https://tsup.egoist.dev/) configuration, open a terminal at the root of the project and execute the [CLI script added previously](#5-add-a-cli-script). A development process should start without outputting any error in the terminal. +To test your new tsup configuration, open a terminal at the root of the project and execute the [CLI script added previously](#5-add-a-cli-script). A development process should start without outputting any error in the terminal. diff --git a/docs/tsup/default.md b/docs/tsup/default.md index 7839372e..49c1ba02 100644 --- a/docs/tsup/default.md +++ b/docs/tsup/default.md @@ -28,7 +28,7 @@ npm create @workleap/project@latest ## TypeScript CLI -Out of the box, `tsc`, the native [TypeScript CLI](https://www.typescriptlang.org/docs/handbook/compiler-options.html), offers pretty much everything that we need to compile and bundle our [TypeScript](https://www.typescriptlang.org/) libraries. We opted for [tsup](https://tsup.egoist.dev/) due to `tsc` lacks of support for CSS imports, a requirement for enabling Chromatic's [TurboSnap](https://www.chromatic.com/docs/turbosnap) feature. +Out of the box, `tsc`, the native [TypeScript CLI](https://www.typescriptlang.org/docs/handbook/compiler-options.html), offers pretty much everything that we need to compile and bundle our TypeScript libraries. We opted for [tsup](https://tsup.egoist.dev/) due to `tsc` lacks of support for CSS imports, a requirement for enabling Chromatic's [TurboSnap](https://www.chromatic.com/docs/turbosnap) feature. Given that either TurboSnap requirements or `tsx` CSS imports support change, we will reevaluate this decision. diff --git a/docs/typescript/advanced-composition.md b/docs/typescript/advanced-composition.md index de564f9b..46b4fbc9 100644 --- a/docs/typescript/advanced-composition.md +++ b/docs/typescript/advanced-composition.md @@ -17,11 +17,11 @@ If the default [by project type configurations](default.md/#available-configurat ## Compose a new configuration -Each configuration piece can be extended individually, or in combination with other pieces, to compose your own custom [TypeScript](https://www.typescriptlang.org/) configuration. +Each configuration piece can be extended individually, or in combination with other pieces, to compose your own custom TypeScript configuration. ### React configuration -To extend the base configuration for a [React](https://react.dev/) project: +To extend the base configuration for a React project: ```json !#2 tsconfig.json { diff --git a/docs/typescript/setup-monorepo.md b/docs/typescript/setup-monorepo.md index df546e5f..c9a6bdfb 100644 --- a/docs/typescript/setup-monorepo.md +++ b/docs/typescript/setup-monorepo.md @@ -114,7 +114,7 @@ Then, open the newly created file and extend the default configuration with one ### web-application -For an applications developed with [React](https://react.dev/), use the following configuration: +For an applications developed with React, use the following configuration: ```json !#2 tsconfig.json { @@ -125,7 +125,7 @@ For an applications developed with [React](https://react.dev/), use the followin ### library -For a library project developed with or without [React](https://react.dev/), use the following configuration: +For a library project developed with or without React, use the following configuration: ```json !#2 tsconfig.json { @@ -199,4 +199,4 @@ If the `packages/components` project is referencing the `packages/utils` project ## 8. Try it :rocket: -To test your new [TypeScript](https://www.typescriptlang.org/) setup, open a TypeScript file, type invalid code (e.g. `import { App } from "./App"`), then wait for the IDE to flag the error. Fix the error (e.g. `import { App } from "./App.tsx"`), then wait for the IDE to remove the error. +To test your new TypeScript setup, open a TypeScript file, type invalid code (e.g. `import { App } from "./App"`), then wait for the IDE to flag the error. Fix the error (e.g. `import { App } from "./App.tsx"`), then wait for the IDE to remove the error. diff --git a/docs/typescript/setup-polyrepo.md b/docs/typescript/setup-polyrepo.md index 4bf05771..03e8f5ab 100644 --- a/docs/typescript/setup-polyrepo.md +++ b/docs/typescript/setup-polyrepo.md @@ -43,7 +43,7 @@ Then, open the newly created file and extend the default configuration with one ### web-application -For an applications developed with [React](https://react.dev/), use the following configuration: +For an applications developed with React, use the following configuration: ```json !#2 tsconfig.json { @@ -54,7 +54,7 @@ For an applications developed with [React](https://react.dev/), use the followin ### library -For a library project developed with or without [React](https://react.dev/), use the following configuration: +For a library project developed with or without React, use the following configuration: ```json !#2 tsconfig.json { @@ -79,4 +79,4 @@ New projects shouldn't have to customize the default configurations offered by ` ## 5. Try it :rocket: -To test your new [TypeScript](https://www.typescriptlang.org/) setup, open a TypeScript file, type invalid code (e.g. `import { App } from "./App"`), then wait for the IDE to flag the error. Fix the error (e.g. `import { App } from "./App.tsx"`), then wait for the IDE to remove the error. +To test your new TypeScript setup, open a TypeScript file, type invalid code (e.g. `import { App } from "./App"`), then wait for the IDE to flag the error. Fix the error (e.g. `import { App } from "./App.tsx"`), then wait for the IDE to remove the error. diff --git a/docs/webpack/configure-build.md b/docs/webpack/configure-build.md index 1ff9f400..f37bfe02 100644 --- a/docs/webpack/configure-build.md +++ b/docs/webpack/configure-build.md @@ -79,7 +79,7 @@ export default defineBuildConfig(swcConfig); ### `swcConfig` -In the previous code sample, the `defineBuildConfig(swcConfig, options)` function receive an [SWC](https://swc.rs) configuration object through the `swcConfig` parameter. +In the previous code sample, the `defineBuildConfig(swcConfig, options)` function receive an SWC [configuration object](https://swc.rs/docs/configuration/swcrc) through the `swcConfig` parameter. Although the [swc-loader](https://swc.rs/docs/usage/swc-loader) defaults to loading the closest `.swcrc` [configuration file](https://swc.rs/docs/configuration/swcrc) when no configuration object is provided, it lacks support for distinct configuration files by environment like webpack does. @@ -207,7 +207,7 @@ export default defineBuildConfig(swcConfig, { ### `plugins` -- **Type**: An array of webpack [plugin](https://webpack.js.org/configuration/plugins/) instances +- **Type**: An array of webpack [plugin instances](https://webpack.js.org/configuration/plugins/) - **Default**: `[]` Append the provided webpack plugins to the configuration. @@ -412,11 +412,11 @@ To create the bundle files for production, add the following script to your proj ## 6. Set environment variables -To deal with environment variables, the [webpack](https://webpack.js.org/) documentation suggests using the [--env option](https://webpack.js.org/guides/environment-variables/) from its CLI. While that would work, by using webpack `--env` CLI option, the environment variables would only be made available to the webpack configuration files (.e.g. `webpack.build.js`) rather than any [Node.js](https://nodejs.org/en) files. Therefore we **do not recommend** using webpack `--env` CLI option. +To deal with environment variables, the webpack documentation suggests using the [--env option](https://webpack.js.org/guides/environment-variables/) from its CLI. While that would work, by using webpack `--env` CLI option, the environment variables would only be made available to the webpack configuration files (.e.g. `webpack.build.js`) rather than any Node.js files. Therefore we **do not recommend** using webpack `--env` CLI option. ### cross-env -We recommend instead to define environment variables using [cross-env](https://github.com/kentcdodds/cross-env). With `cross-env`, the environment variables will be made available to any [Node.js](https://nodejs.org/en) files that are executed by the script process (`dev` in the example below :point_down:): +We recommend instead to define environment variables using [cross-env](https://github.com/kentcdodds/cross-env). With `cross-env`, the environment variables will be made available to any Node.js files that are executed by the script process (`dev` in the example below :point_down:): ```json package.json { @@ -479,4 +479,4 @@ The `=== "true"` part of `"DEBUG": process.env.DEBUG === "true"` is very importa ## 7. Try it :rocket: -To test your new [webpack](https://webpack.js.org/) configuration, open a terminal at the root of the project and execute the [CLI script added earlier](#5-add-a-cli-script). The build process should complete without outputting any error in the terminal and the bundle files should be available in the `/dist` folder (or any other `outputPath` you configured). +To test your new webpack configuration, open a terminal at the root of the project and execute the [CLI script added earlier](#5-add-a-cli-script). The build process should complete without outputting any error in the terminal and the bundle files should be available in the `/dist` folder (or any other `outputPath` you configured). diff --git a/docs/webpack/configure-dev.md b/docs/webpack/configure-dev.md index 2deb6209..bb9237df 100644 --- a/docs/webpack/configure-dev.md +++ b/docs/webpack/configure-dev.md @@ -79,7 +79,7 @@ export default defineDevConfig(swcConfig); ### `swcConfig` -In the previous code sample, the `defineDevConfig(swcConfig, options)` function receive an [SWC](https://swc.rs) configuration object through the `swcConfig` parameter. +In the previous code sample, the `defineDevConfig(swcConfig, options)` function receive an SWC [configuration object](https://swc.rs/docs/configuration/swcrc) through the `swcConfig` parameter. Although the [swc-loader](https://swc.rs/docs/usage/swc-loader) defaults to loading the closest `.swcrc` [configuration file](https://swc.rs/docs/configuration/swcrc) when no configuration object is provided, it lacks support for distinct configuration files by environment like webpack does. @@ -223,7 +223,7 @@ export default defineDevConfig(swcConfig, { ### `plugins` -- **Type**: An array of webpack [plugin](https://webpack.js.org/configuration/plugins/) instances +- **Type**: An array of webpack [plugin instances](https://webpack.js.org/configuration/plugins/) - **Default**: `[]` Append the provided webpack plugins to the configuration. @@ -427,11 +427,11 @@ To initiate the development server, add the following script to your project `pa ## 6. Set environment variables -To deal with environment variables, the [webpack](https://webpack.js.org/) documentation suggests using the [--env option](https://webpack.js.org/guides/environment-variables/) from its CLI. While that would work, by using webpack `--env` CLI option, the environment variables would only be made available to the webpack configuration files (.e.g. `webpack.dev.js`) rather than any [Node.js](https://nodejs.org/en) files. Therefore we **do not recommend** using webpack `--env` CLI option. +To deal with environment variables, the webpack documentation suggests using the [--env option](https://webpack.js.org/guides/environment-variables/) from its CLI. While that would work, by using webpack `--env` CLI option, the environment variables would only be made available to the webpack configuration files (.e.g. `webpack.dev.js`) rather than any Node.js files. Therefore we **do not recommend** using webpack `--env` CLI option. ### cross-env -We recommend instead to define environment variables using [cross-env](https://github.com/kentcdodds/cross-env). With `cross-env`, the environment variables will be made available to any [Node.js](https://nodejs.org/en) files that are executed by the script process (`dev` in the example below :point_down:): +We recommend instead to define environment variables using [cross-env](https://github.com/kentcdodds/cross-env). With `cross-env`, the environment variables will be made available to any Node.js files that are executed by the script process (`dev` in the example below :point_down:): ```json package.json { @@ -494,6 +494,6 @@ The `=== "true"` part of `"DEBUG": process.env.DEBUG === "true"` is very importa ## 7. Try it :rocket: -To test your new [webpack](https://webpack.js.org/) configuration, open a terminal at the root of the project and execute the [CLI script added earlier](#5-add-a-cli-script). A development server should start without outputting any error in the terminal. +To test your new webpack configuration, open a terminal at the root of the project and execute the [CLI script added earlier](#5-add-a-cli-script). A development server should start without outputting any error in the terminal. diff --git a/docs/webpack/default.md b/docs/webpack/default.md index 201166f7..9dd11814 100644 --- a/docs/webpack/default.md +++ b/docs/webpack/default.md @@ -28,7 +28,7 @@ npm create @workleap/project@latest ## A word about Rspack -[Rspack](https://www.rspack.dev/) is a partial rewrite of [webpack](https://webpack.js.org/) in [Rust](https://foundation.rust-lang.org/) and will most likely be its successor once it's features complete and stable. Our goal is to migrate to Rspack somewhere in 2024 when [Module Federation](https://module-federation.io/) support will be available. +[Rspack](https://www.rspack.dev/) is a partial rewrite of [webpack](https://webpack.js.org/) in Rust and will most likely be its successor once it's features complete and stable. Our goal is to migrate to Rspack somewhere in 2024 when [Module Federation](https://module-federation.io/) support will be available. Meanwhile, you can **confidently start a new project with webpack** as the **migration** process to Rspack is expected to be **seamless**; Rspack is committed to support the full webpack API and its massive plugin ecosystem.