feat: Added baseUrl and paths predefined options to SWC

.changeset/gold-pans-flash.md

@@ -0,0 +1,5 @@
+---
+"@workleap/swc-configs": minor
+---
+
+Added the `baseUrl` and `paths` predefined options.

docs/eslint/setup-monorepo.md

@@ -83,6 +83,8 @@ Then, open the newly created file and paste the following ignore rules:
 ```bash .eslintignore
 **/dist/*
 node_modules
+__snapshots__
+storybook-static
 *.md
 *.yml
 *.yaml

docs/eslint/setup-polyrepo.md

@@ -99,6 +99,8 @@ Then, open the newly created file and paste the following ignore rules:
 ```bash .eslintignore
 **/dist/*
 node_modules
+__snapshots__
+storybook-static
 *.md
 *.yml
 *.yaml

docs/stylelint/setup-monorepo.md

@@ -82,6 +82,8 @@ Then, open the newly created file and paste the following ignore rules:
 ```bash .stylelintignore
 **/dist/*
 node_modules
+storybook-static
+!.storybook
 ```
 
 #### .prettierignore
@@ -108,7 +110,6 @@ Then, open the newly created file and paste the following ignore rules:
 ``` .prettierignore
 *
 !**/*.css
-!.storybook
 ```
 
 ### Configure the indent style

docs/stylelint/setup-polyrepo.md

@@ -70,6 +70,8 @@ Then, open the newly created file and paste the following ignore rules:
 ```bash .stylelintignore
 **/dist/*
 node_modules
+storybook-static
+!.storybook
 ```
 
 ### .prettierignore
@@ -93,7 +95,6 @@ Then, open the newly created file and paste the following ignore rules:
 ``` .prettierignore
 *
 !**/*.css
-!.storybook
 ```
 
 ## Configure indent style

docs/swc/configure-build.md

@@ -105,6 +105,25 @@ The `browserslistToSwc(options)` utility function accepts any option supported b
 
 The `defineBuildConfig(targets, options)` function can be used as shown in the previous example, however, if you wish to customize the default configuration, the function also accept a few predefined options to help with that 👇
 
+### `baseUrl`
+
+- **Type**: `string`
+
+Sets a base directory from which to resolve module names. This option is usually provided when custom [paths](#paths) are provided. Note that SWC requires the `baseUrl` to be an absolute path.
+
+```js !#9 swc.build.js
+// @ts-check
+
+import path from "node:path";
+import { browserslistToSwc, defineBuildConfig } from "@workleap/swc-configs";
+
+const targets = browserslistToSwc();
+
+export const swcConfig = defineBuildConfig(targets, {
+    baseUrl: path.resolve("src")
+});
+```
+
 ### `parser`
 
 - **Type**: `"ecmascript" | "typescript"`
@@ -124,6 +143,28 @@ export const swcConfig = defineBuildConfig(targets, {
 });
 ```
 
+### `paths`
+
+- **Type**: `Record<string, string[]>`
+
+A series of entries which re-map imports to lookup locations relative to the [baseUrl](#baseurl) if set.
+
+```js !#10-12 swc.dev.js
+// @ts-check
+
+import path from "node:path";
+import { browserslistToSwc, defineBuildConfig } from "@workleap/swc-configs";
+
+const targets = browserslistToSwc();
+
+export const swcConfig = defineBuildConfig(targets, {
+    baseUrl: path.resolve("src"),
+    paths: {
+        "@/*": ["*"]
+    }
+});
+```
+
 ## Configuration transformers
 
 !!!warning
@@ -143,14 +184,17 @@ To view the default development configuration of `@workleap/swc-configs`, have a
 transformer(config: SwcConfig, context: SwcConfigTransformerContext) => SwcConfig
 ```
 
-```js !#7-11,14 swc.build.js
+```js !#10-14,17 swc.build.js
 // @ts-check
 
-import { browserslistToSwc, defineBuildConfig, type SwcConfigTransformer, type SwcConfig } from "@workleap/swc-configs";
+import { browserslistToSwc, defineBuildConfig } from "@workleap/swc-configs";
 
 const targets = browserslistToSwc();
 
-const mangleMinifiedCode: SwcConfigTransformer = (config: SwcConfig) => {
+/**
+ * @type {import("@workleap/swc-configs").SwcConfigTransformer}
+ */
+function mangleMinifiedCode(config) {
     config.jsc.minify.mangle = true;
 
     return config;
@@ -165,10 +209,13 @@ export const swcConfig = defineBuildConfig(targets, {
 
 Generic transformers can use the `context` parameter to gather additional information about their execution context, like the `environment` they are operating in:
 
-```ts !#4 transformer.ts
-import type { SwcConfigTransformer, SwcConfigTransformerContext, SwcConfig } from "@workleap/swc-configs";
+```ts !#7 transformer.js
+// @ts-check
 
-export const transformer: SwcConfigTransformer = (config: SwcConfig, context: SwcConfigTransformerContext) => {
+/**
+ * @type {import("@workleap/swc-configs").SwcConfigTransformer}
+ */
+export function transformer(config, context) {
     if (context.environment === "build") {
         config.jsc.minify.mangle = true;
     }

docs/swc/configure-dev.md

@@ -105,6 +105,25 @@ The `browserslistToSwc(options)` utility function accepts any option supported b
 
 The `defineDevConfig(targets, options)` function can be used as shown in the previous example, however, if you wish to customize the default configuration, the function also accept a few predefined options to help with that 👇
 
+### `baseUrl`
+
+- **Type**: `string`
+
+Sets a base directory from which to resolve module names. This option is usually provided when custom [paths](#paths) are provided. Note that SWC requires the `baseUrl` to be an absolute path.
+
+```js !#9 swc.dev.js
+// @ts-check
+
+import path from "node:path";
+import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";
+
+const targets = browserslistToSwc();
+
+export const swcConfig = defineDevConfig(targets, {
+    baseUrl: path.resolve("src")
+});
+```
+
 ### `fastRefresh`
 
 - **Type**: `boolean`
@@ -143,6 +162,28 @@ export const swcConfig = defineDevConfig(targets, {
 });
 ```
 
+### `paths`
+
+- **Type**: `Record<string, string[]>`
+
+A series of entries which re-map imports to lookup locations relative to the [baseUrl](#baseurl) if set.
+
+```js !#10-12 swc.dev.js
+// @ts-check
+
+import path from "node:path";
+import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";
+
+const targets = browserslistToSwc();
+
+export const swcConfig = defineDevConfig(targets, {
+    baseUrl: path.resolve("src"),
+    paths: {
+        "@/*": ["*"]
+    }
+});
+```
+
 ## Configuration transformers
 
 !!!warning
@@ -162,14 +203,17 @@ To view the default development configuration of `@workleap/swc-configs`, have a
 transformer(config: SwcConfig, context: SwcConfigTransformerContext) => SwcConfig
 ```
 
-```js !#7-11,14 swc.dev.js
+```js !#10-14,17 swc.dev.js
 // @ts-check
 
-import { browserslistToSwc, defineDevConfig, type SwcConfigTransformer, type SwcConfig } from "@workleap/swc-configs";
+import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";
 
 const targets = browserslistToSwc();
 
-const disableReactBuiltins: SwcConfigTransformer = (config: SwcConfig) => {
+/**
+ * @type {import("@workleap/swc-configs").SwcConfigTransformer}
+ */
+function disableReactBuiltins(config) {
     config.jsc.transform.react.useBuiltins = false;
 
     return config;
@@ -184,10 +228,13 @@ export const swcConfig = defineDevConfig(targets, {
 
 Generic transformers can use the `context` parameter to gather additional information about their execution context, like the `environment` they are operating in:
 
-```ts !#4 transformer.ts
-import type { SwcConfigTransformer, SwcConfigTransformerContext, SwcConfig } from "@workleap/swc-configs";
+```ts !#7 transformer.js
+// @ts-check
 
-export const transformer: SwcConfigTransformer = (config: SwcConfig, context: SwcConfigTransformerContext) => {
+/**
+ * @type {import("@workleap/swc-configs").SwcConfigTransformer}
+ */
+export function transformer(config, context) {
     if (context.environment === "dev") {
         config.jsc.transform.react.useBuiltins = false;
     }

docs/swc/configure-jest.md

@@ -58,6 +58,25 @@ export const swcConfig = defineJestConfig();
 
 The `defineJestConfig(options)` function can be used as shown in the previous example, however, if you wish to customize the default configuration, the function also accept a few predefined options to help with that 👇
 
+### `baseUrl`
+
+- **Type**: `string`
+
+Sets a base directory from which to resolve module names. This option is usually provided when custom [paths](#paths) are provided. Note that SWC requires the `baseUrl` to be an absolute path.
+
+```js !#9 swc.build.js
+// @ts-check
+
+import path from "node:path";
+import { browserslistToSwc, defineJestConfig } from "@workleap/swc-configs";
+
+const targets = browserslistToSwc();
+
+export const swcConfig = defineJestConfig(targets, {
+    baseUrl: path.resolve("src")
+});
+```
+
 ### `react`
 
 - **Type**: `boolean`
@@ -88,6 +107,28 @@ export const swcConfig = defineJestConfig({
 });
 ```
 
+### `paths`
+
+- **Type**: `Record<string, string[]>`
+
+A series of entries which re-map imports to lookup locations relative to the [baseUrl](#baseurl) if set.
+
+```js !#10-12 swc.dev.js
+// @ts-check
+
+import path from "node:path";
+import { browserslistToSwc, defineJestConfig } from "@workleap/swc-configs";
+
+const targets = browserslistToSwc();
+
+export const swcConfig = defineJestConfig(targets, {
+    baseUrl: path.resolve("src"),
+    paths: {
+        "@/*": ["*"]
+    }
+});
+```
+
 ## Configuration transformers
 
 !!!warning

docs/typescript/setup-monorepo.md

@@ -59,13 +59,13 @@ Then, open the newly created file and extend the default configuration with the
 }
 ```
 
-If your application is using [Storybook](https://storybook.js.org/), make sure to include the `.storybook` folder:
+If your application is using [Storybook](https://storybook.js.org/), make sure to include the `.storybook` folder and exclude the `.storybook/storybook-static` folder:
 
 ```json !#3 tsconfig.json
 {
     "extends": "@workleap/typescript-configs/monorepo-workspace.json",
     "include": ["**/*", ".storybook/*"],
-    "exclude": ["packages", "node_modules"]
+    "exclude": ["packages", "node_modules", ".storybook/storybook-static"]
 }
 ```
 

docs/typescript/setup-polyrepo.md

@@ -75,13 +75,13 @@ For a library project developed with or without React, use the following configu
 }
 ```
 
-If your application is using [Storybook](https://storybook.js.org/), make sure to include the `.storybook` folder:
+If your application is using [Storybook](https://storybook.js.org/), make sure to include the `.storybook` folder and exclude the `.storybook/storybook-static` folder:
 
-```json !#3 tsconfig.json
+```json !#3-4 tsconfig.json
 {
     "extends": ["@workleap/typescript-configs/library.json"],
     "include": ["**/*", ".storybook/*"],
-    "exclude": ["dist", "node_modules"]
+    "exclude": ["dist", "node_modules", ".storybook/storybook-static"]
 }
 ```
 

docs/webpack/configure-build.md

@@ -416,13 +416,16 @@ To view the default build configuration of `@workleap/webpack-configs`, have a l
 transformer(config: WebpackConfig, context: WebpackConfigTransformerContext) => WebpackConfig
 ```
 
-```js !#6-10,13 webpack.build.js
+```js !#9-13,16 webpack.build.js
 // @ts-check
 
-import { defineBuildConfig, type WebpackConfigTransformer, type WebpackConfig } from "@workleap/webpack-configs";
+import { defineBuildConfig } from "@workleap/webpack-configs";
 import { swcConfig } from "./swc.build.js";
 
-const useContentHashOutputFilename: WebpackConfigTransformer = (config: WebpackConfig) => {
+/**
+ * @type {import("@workleap/webpack-configs").WebpackConfigTransformer}
+ */
+function useContentHashOutputFilename(config) {
     config.output.filename = "[name].[contenthash].bundle.js";
 
     return config;
@@ -437,10 +440,13 @@ export default defineBuildConfig(swcConfig, {
 
 Generic transformers can use the `context` parameter to gather additional information about their execution context, like the `environment` they are operating in:
 
-```ts !#4 transformer.ts
-import type { WebpackConfigTransformer, WebpackConfigTransformerContext, WebpackConfig } from "@workleap/webpack-configs";
+```ts !#7 transformer.js
+// @ts-check
 
-export const transformer: WebpackConfigTransformer = (config: WebpackConfig, context: WebpackConfigTransformerContext) => {
+/**
+ * @type {import("@workleap/webpack-configs").WebpackConfigTransformer}
+ */
+export function transformer(config, context) {
     if (context.environment === "build") {
         config.output.filename = "[name].[contenthash].bundle.js";
     }