@workleap/swc-configs 0.0.1 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @workleap/swc-configs
+
+## 1.0.0
+
+### Major Changes
+
+- [#85](https://github.com/workleap/wl-web-configs/pull/85) [`bad2df7`](https://github.com/workleap/wl-web-configs/commit/bad2df75593fb70d431d73bdced653b157c50caa) Thanks [@patricklafrance](https://github.com/patricklafrance)! - Updated TSUP configuration and added a new SWC config package

package/README.md

@@ -26,50 +26,63 @@ npm install -D @workleap/swc-configs @swc/core @swc/helpers
 
 ### Dev
 
-Create a `swc.dev.ts` file at the root of your project:
+Create a `swc.dev.js` file at the root of your project:
 
 ```
 root
 |---/src
-|---swc.dev.ts
+|---swc.dev.js
+|---webpack.dev.js
 ```
 
-Then, in the newly created file, import and execute the `defineDevConfig` function to return a valid SWC configuration object:
+Then, in the newly created file, import and execute the `defineDevConfig` function to export a valid SWC configuration object:
 
 ```ts
-// swc.dev.ts
+// swc.dev.js
 
 import { defineDevConfig } from "@workleap/swc-configs";
 
-return defineDevConfig();
+export const swcConfig = defineDevConfig();
 ```
 
 Finally, install the Webpack [swc-loader](https://swc.rs/docs/usage/swc-loader) package and add the following `rule` to your Webpack configuration:
 
 ```js
-{
-    test: /\.(ts|tsx)/i,
-    exclude: /node_modules/,
-    use: {
-        loader: "swc-loader"
+// webpack.dev.js
+
+// @ts-check
+
+import { swcConfig } from "./swc.dev.js";
+
+/** @type {import("webpack").Configuration} */
+export default {
+    module: {
+        rules: {
+            test: /\.(ts|tsx)/i,
+            exclude: /node_modules/,
+            use: {
+                loader: "swc-loader",
+                options: swcConfig
+            }
+        }
     }
 }
 ```
 
-> The rule declaration may vary depending of your project configuration. For example, you might change the `test` property to target ECMAScript files instead: `test: /\.(js|jsx)/i`.
+> The rule declaration may vary depending of your project configuration. For example, you might want to change the `test` property to target ECMAScript files instead: `test: /\.(js|jsx)/i`.
 
-#### Customize the configuration
+#### Customizing the configuration
 
-If you wish to customize the default development configuration, there a few options.
+If you wish to customize the default development configuration, there are a few possibilities.
 
 ##### Use predefined options
 
-The `defineDevConfig` function accepts a few convivial options to customize the default SWC configuration without having to learn any [SWC specific configuration syntax](https://swc.rs/docs/configuration/swcrc) or mangling with complicated options.
+The `defineDevConfig` function accepts predefined options to customize the default SWC configuration without having to learn any [SWC specific configuration syntax](https://swc.rs/docs/configuration/swcrc) or mangling with complicated configuration properties.
 
 To enable [React fast refresh](https://github.com/pmmmwh/react-refresh-webpack-plugin), use the `fastRefresh` option:
 
 ```ts
-// swc.dev.ts
+// swc.dev.js
 
 import { defineDevConfig } from "@workleap/swc-configs";
 
@@ -80,10 +93,10 @@ return defineDevConfig({
 
 > Don't forget to install [ReactRefreshWebpackPlugin](https://github.com/pmmmwh/react-refresh-webpack-plugin) and update your Webpack configuration accordingly.
 
-By default the development configuration expect to parse TypeScript code. If your project is coded with regular JavaScript (ECMAScript), use the `parser` option to tell SWC to expect regular JavaScript code rather than TypeScript code:
+The development configuration expect to parse TypeScript code. If your project is coded with regular JavaScript (ECMAScript), use the `parser` option to configure SWC to parse regular JavaScript code rather than TypeScript code:
 
 ```ts
-// swc.dev.ts
+// swc.dev.js
 
 import { defineDevConfig } from "@workleap/swc-configs";
 
@@ -92,13 +105,187 @@ return defineDevConfig({
 });
 ```
 
-##### Provide a custom configuration object
+##### Manually overriding SWC configuration
+
+Refer to the [configuration override](#configuration-override) section.
+
+### Build
+
+Create a `swc.build.js` file at the root of your project:
+
+```
+root
+|---/src
+|---swc.build.js
+|---webpack.build.js
+```
+
+Then, in the newly created file, import and execute the `defineBuildConfig` function to export a valid SWC configuration object:
+
+```ts
+// swc.build.js
+
+import { defineBuildConfig } from "@workleap/swc-configs";
+
+export const swcConfig = defineBuildConfig();
+```
+
+Finally, install the Webpack [swc-loader](https://swc.rs/docs/usage/swc-loader) package and add the following `rule` to your Webpack configuration:
+
+```js
+// webpack.build.js
+
+// @ts-check
+
+import { swcConfig } from "./swc.build.js";
+
+/** @type {import("webpack").Configuration} */
+export default {
+    module: {
+        rules: {
+            test: /\.(ts|tsx)/i,
+            exclude: /node_modules/,
+            use: {
+                loader: "swc-loader",
+                options: swcConfig
+            }
+        }
+    }
+}
+```
+
+#### Customizing the configuration
+
+If you wish to customize the default build configuration, there are a few possibilities.
+
+##### Use predefined options
+
+The `defineBuildConfig` function accepts predefined options to customize the default SWC configuration without having to learn any [SWC specific configuration syntax](https://swc.rs/docs/configuration/swcrc) or mangling with complicated configuration properties.
+
+The build configuration expect to parse TypeScript code. If your project is coded with regular JavaScript (ECMAScript), use the `parser` option to configure SWC to parse regular JavaScript code rather than TypeScript code:
+
+```ts
+// swc.build.js
+
+import { defineBuildConfig } from "@workleap/swc-configs";
+
+return defineBuildConfig({
+    parser: "ecmascript"
+});
+```
+
+##### Manually overriding SWC configuration
+
+Refer to the [configuration override](#configuration-override) section.
+
+### Jest
+
+#### Installation
+
+First install the following package:
+
+**With pnpm**
+
+```shell
+pnpm add -D @swc/jest
+```
+
+**With yarn**
+
+```shell
+yarn add -D @swc/jest
+```
+
+**With npm**
+
+```shell
+yarn add -D @swc/jest
+```
+
+#### Usage
+
+Create a `swc.jest.ts` file at the root of your project:
+
+```
+root
+|---/src
+|---swc.jest.ts
+|---jest.config.ts
+```
+
+Then, in the newly created file, import and execute the `defineJestConfig` function to export a valid SWC configuration object:
+
+```ts
+// swc.jest.ts
+
+import { defineJestConfig } from "@workleap/swc-configs";
+
+export const swcConfig = defineJestConfig();
+```
+
+Finally, add the following Jest [code transform](https://jestjs.io/docs/code-transformation) to your `jest.config.ts` file:
+
+```js
+// jest.config.ts
+
+import { swcCnfig } from "./swc.jest.ts";
+
+const config = {
+    transform: {
+        "^.+\\.(ts|tsx)$": ["@swc/jest", swcConfig as Record<string, unknown>]
+    }
+};
+```
+
+> The transform declaration may vary depending of your project configuration. For example, you might want to change the file extensions to target ECMAScript files instead: `^.+\\.(js|jsx)$`.
+
+#### Customizing the configuration
+
+If you wish to customize the default Jest configuration, there are a few possibilities.
+
+##### Use predefined options
+
+The `defineJestConfig` function accepts predefined options to customize the default SWC configuration without having to learn any [SWC specific configuration syntax](https://swc.rs/docs/configuration/swcrc) or mangling with complicated configuration properties.
+
+The default Jest configuration doesn't include React. To include React, use the `react` option:
+
+```ts
+// swc.jest.ts
+
+import { defineJestConfig } from "@workleap/swc-configs";
+
+return defineJestConfig({
+    react: true
+});
+```
+
+The Jest configuration expect to parse TypeScript code. If your project is coded with regular JavaScript (ECMAScript), use the `parser` option to configure SWC to parse regular JavaScript code rather than TypeScript code:
+
+```ts
+// swc.jest.ts
+
+import { defineJestConfig } from "@workleap/swc-configs";
+
+return defineJestConfig({
+    parser: "ecmascript"
+});
+```
+
+##### Manually overriding SWC configuration
+
+Refer to the [configuration override](#configuration-override) section.
+
+### Configuration override
+
+> This documentation section will use the [Dev configuration](#dev) `defineDevConfig` function and `DefaultDevConfig` object to showcase examples but keep in mind that it also available for the [Build](#build) and [Jest](#jest) configurations.
 
-The `defineDevConfig` function also accepts a `configOverride` property. This property allow you to override any options of the default development configuration. It's important to note that the provided configuration object **will not** merge with the default configuration, it will override any matching properties of the default configuration.
+All "define" functions accepts a `configOverride` property. This property allow the consumer to override any property of the default SWC configuration. The `configOverride` supports 2 syntaxes, a [custom object](#custom-object) and a [function](#function).
 
-> Prefer using [predefined options](#use-predefined-options) whenever possible.
+It's important to note that with both syntaxes, the provided configuration **will not** be merged with the default configuration, it will override any matching properties of the default configuration.
 
-Given the following code:
+#### Custom object
+
+The easiest way to override manually the SWC config is with the object syntax:
 
 ```ts
 // swc.dev.ts
@@ -116,7 +303,7 @@ return defineDevConfig({
 });
 ```
 
-The whole `jsx` section of the default configuration would be overrided for:
+In the previous example, the whole `jsx` section of the default configuration would be overrided for:
 
 ```js
 jsc: {
@@ -126,7 +313,7 @@ jsc: {
 }
 ```
 
-To extend the default configuration options rather than overriding them, use the `DefaultDevConfig` object to merge additional options with the default configuration:
+While in some cases it's fine, often a consumer would prefer to extend the default configuration rather than overriding it's properties. To extend the configuration, use the `DefaultDevConfig` object to merge new properties with the default configuration properties:
 
 ```ts
 // swc.dev.ts
@@ -145,9 +332,9 @@ return defineDevConfig({
 });
 ```
 
-##### Using a function to customize the final configuration object
+##### Function
 
-The `configOverride` property also accept a function. While there are a wide range of additional use cases that can be solved by using a function rather than an object, the main purpose of supporting a function here is to allow mixing [predefined options](#use-predefined-options) with a custom configuration object.
+The `configOverride` property also accept a function. While there are a wide range of additional use cases that can be solved with a function, the main purpose of using a function here is to allow mixing **predefined options** with a **custom configuration object**.
 
 Take the following example:
 
@@ -169,13 +356,13 @@ return defineDevConfig({
 });
 ```
 
-The consumer wish to enable [React fast refresh](https://github.com/pmmmwh/react-refresh-webpack-plugin) and ESM dynamic imports. That's a good idea to use the `fastRefresh` [predefined options](#use-predefined-options) to enable fast refresh. Since there are no predefined option to enable ESM dynamic imports, a custom configuration object must be provided to extend the `jsc.parser` section with the `dynamicImport` property.
+In this example, the consumer wish to enable [React fast refresh](https://github.com/pmmmwh/react-refresh-webpack-plugin) and ESM dynamic imports. That's a good idea to use the `fastRefresh` predefined options to enable fast refresh. However, since there are no predefined option to enable ESM dynamic imports, a custom configuration object must be provided to extend the `jsc.parser` section with the `dynamicImport` property.
 
-Given that the consumer extends the configuration rather than overriding it, we could expect that the React fast refresh configuration will be included in the final configuration.
+Given that the consumer extends the configuration rather than overriding it, one could expect that the React fast refresh configuration will be included in the final configuration.
 
-Wrong, the React fast refresh configuration won't be included because it's not part of the `DefaultDevConfig` object.
+Wrong, the React fast refresh configuration won't be included because it's not part of the `DefaultDevConfig` object that the consumer is extending.
 
-To extend the default development configuration and support predefined options, you must provide a function rather than an object:
+To extend the default development configuration and also use predefined options, you must provide a function rather than an object:
 
 ```ts
 // swc.dev.ts
@@ -198,13 +385,7 @@ return defineDevConfig({
 });
 ```
 
-Using a function allow the consumer to receive as argument a configuration object derived from the `DefaultDevConfig` including any additional configuration added with [predefined options](#use-predefined-options).
-
-### Build
-
-### Jest
-
-### Configuration override
+Using a function allow the consumer to receive as argument a configuration object derived from the `DefaultDevConfig` object, including any additional properties added with predefined options.
 
 ## Maintainers notes
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@workleap/swc-configs",
   "description": "Workleap recommended SWC configs.",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "license": "Apache-2.0",
   "keywords": [
     "workleap",
@@ -34,9 +34,9 @@
     "ts-node": "10.9.1",
     "tsup": "6.7.0",
     "typescript": "5.0.4",
-    "@workleap/eslint-plugin": "1.8.1",
-    "@workleap/tsup-configs": "1.0.1",
-    "@workleap/typescript-configs": "2.3.1"
+    "@workleap/eslint-plugin": "1.8.2",
+    "@workleap/tsup-configs": "2.0.0",
+    "@workleap/typescript-configs": "2.3.2"
   },
   "peerDependencies": {
     "@swc/core": "*",