From 10734d4a21d75ba65c126ea1bcb7b8a7c3114f84 Mon Sep 17 00:00:00 2001 From: Patrick Lu Date: Sat, 29 Nov 2025 11:43:58 -0800 Subject: [PATCH] docs: Document Next.js @ alias fallback behavior MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive JSDoc comments explaining the automatic @ alias detection in the webpack plugin's getAliasMap method. The fallback behavior: - Only activates when no @ alias is found in tsconfig or webpack config - Assumes Next.js convention: @/* -> ./src/* - Requires a src directory to exist in the project root This documentation helps users understand: - When the auto-detection applies - How to override it for non-Next.js projects - The recommended approach using tsconfig.json paths 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- src/webpack-plugin.ts | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/src/webpack-plugin.ts b/src/webpack-plugin.ts index f445b36..c0984dc 100644 --- a/src/webpack-plugin.ts +++ b/src/webpack-plugin.ts @@ -158,7 +158,25 @@ export default class CodePressWebpackPlugin { console.warn("[CodePress] Error reading tsconfig.json:", e); } - // Fallback: Next.js convention is @/* -> ./src/* + /** + * Fallback: Auto-detect Next.js @ alias based on directory structure. + * + * This fallback only applies when: + * 1. No @ alias was found in tsconfig.json paths + * 2. No @ alias was found in webpack resolve.alias + * 3. A "src" directory exists in the project root + * + * Next.js projects commonly use the convention: + * @/* -> ./src/* + * + * This allows imports like: + * import { Button } from "@/components/Button" + * + * For non-Next.js projects or custom project structures: + * - Explicit configuration is recommended via tsconfig.json paths + * - Example: { "compilerOptions": { "paths": { "@/*": ["./app/*"] } } } + * - This fallback will be skipped if you define your own @ alias + */ if (!aliases.has("@")) { const srcDir = path.join(compiler.context, "src"); if (fs.existsSync(srcDir)) {