diff --git a/docs/swc/configure-build.md b/docs/swc/configure-build.md
index b0cd4c76..db8521ac 100644
--- a/docs/swc/configure-build.md
+++ b/docs/swc/configure-build.md
@@ -145,6 +145,10 @@ export const swcConfig = defineBuildConfig(targets, {
 
 ### `paths`
 
+!!!warning
+You shouldn't need to define custom paths for your project. If you're defining custom paths to support aliases, consider using the [imports](https://medium.com/outbrain-engineering/the-hidden-power-of-package-json-a93143ec0b7c) field of your project's `package.json` file instead.
+!!!
+
 - **Type**: `Record<string, string[]>`
 
 A series of entries which re-map imports to lookup locations relative to the [baseUrl](#baseurl) if set.
diff --git a/docs/swc/configure-dev.md b/docs/swc/configure-dev.md
index 4c7a54e2..77a17ee5 100644
--- a/docs/swc/configure-dev.md
+++ b/docs/swc/configure-dev.md
@@ -164,6 +164,10 @@ export const swcConfig = defineDevConfig(targets, {
 
 ### `paths`
 
+!!!warning
+You shouldn't need to define custom paths for your project. If you're defining custom paths to support aliases, consider using the [imports](https://medium.com/outbrain-engineering/the-hidden-power-of-package-json-a93143ec0b7c) field of your project's `package.json` file instead.
+!!!
+
 - **Type**: `Record<string, string[]>`
 
 A series of entries which re-map imports to lookup locations relative to the [baseUrl](#baseurl) if set.
diff --git a/docs/swc/configure-jest.md b/docs/swc/configure-jest.md
index 898ea616..8797105f 100644
--- a/docs/swc/configure-jest.md
+++ b/docs/swc/configure-jest.md
@@ -109,6 +109,10 @@ export const swcConfig = defineJestConfig({
 
 ### `paths`
 
+!!!warning
+You shouldn't need to define custom paths for your project. If you're defining custom paths to support aliases, consider using the [imports](https://medium.com/outbrain-engineering/the-hidden-power-of-package-json-a93143ec0b7c) field of your project's `package.json` file instead.
+!!!
+
 - **Type**: `Record<string, string[]>`
 
 A series of entries which re-map imports to lookup locations relative to the [baseUrl](#baseurl) if set.