feat(cli): auto-detect Next.js and suggest correct default install paths

packages/cli/src/commands/init.ts

@@ -10,6 +10,31 @@ import { generateThemeContextFile, generateThemeFile } from '../utils/generate-t
 import { ensureReactPdfRenderer } from '../utils/install-dependencies.js';
 import { displayPreFlightResults, runPreFlightChecks } from '../utils/pre-flight.js';
 import { normalizeThemePath, validateThemePath } from '../utils/theme-path.js';
+import { detectNextJs } from '../utils/environment-validator.js';
+
+/**
+ * Return context-aware default paths.
+ * For Next.js projects without a `src/` directory, drop the `src/` prefix so
+ * the suggested paths match the project's actual layout.
+ */
+function getSmartDefaults(cwd: string = process.cwd()) {
+  const isNextJs = detectNextJs(cwd);
+  const hasSrcDir = fs.existsSync(path.join(cwd, 'src'));
+
+  if (isNextJs && !hasSrcDir) {
+    return {
+      componentDir: './components/pdfx',
+      blockDir: './blocks/pdfx',
+      themeFile: './lib/pdfx-theme.ts',
+    };
+  }
+
+  return {
+    componentDir: DEFAULTS.COMPONENT_DIR,
+    blockDir: DEFAULTS.BLOCK_DIR,
+    themeFile: DEFAULTS.THEME_FILE,
+  };
+}
 
 interface InitOptions {
   /** Skip all prompts and accept defaults. Suitable for CI / non-interactive environments. */
@@ -56,21 +81,22 @@ export async function init(options: InitOptions = {}) {
   }
 
   // In --yes mode, skip all prompts and use sensible defaults.
+  const defaults = getSmartDefaults();
   const answers = options.yes
     ? {
-        componentDir: DEFAULTS.COMPONENT_DIR,
-        blockDir: DEFAULTS.BLOCK_DIR,
+        componentDir: defaults.componentDir,
+        blockDir: defaults.blockDir,
         registry: DEFAULTS.REGISTRY_URL,
         themePreset: 'professional' as const,
-        themePath: normalizeThemePath(DEFAULTS.THEME_FILE),
+        themePath: normalizeThemePath(defaults.themeFile),
       }
     : await prompts(
         [
           {
             type: 'text',
             name: 'componentDir',
             message: 'Where should we install components?',
-            initial: DEFAULTS.COMPONENT_DIR,
+            initial: defaults.componentDir,
             validate: (value: string) => {
               if (!value || value.trim().length === 0) {
                 return 'Component directory is required';
@@ -90,7 +116,7 @@ export async function init(options: InitOptions = {}) {
             type: 'text',
             name: 'blockDir',
             message: 'Where should we install blocks?',
-            initial: DEFAULTS.BLOCK_DIR,
+            initial: defaults.blockDir,
             validate: (value: string) => {
               if (!value || value.trim().length === 0) {
                 return 'Block directory is required';
@@ -143,7 +169,7 @@ export async function init(options: InitOptions = {}) {
             type: 'text',
             name: 'themePath',
             message: 'Where should we create the theme file?',
-            initial: DEFAULTS.THEME_FILE,
+            initial: defaults.themeFile,
             format: normalizeThemePath,
             validate: validateThemePath,
           },

packages/cli/src/utils/environment-validator.test.ts

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  detectNextJs,
+  validatePackageJson,
+  validateReactProject,
+} from './environment-validator.js';
+
+describe('environment-validator', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pdfx-env-test-'));
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  function writePackageJson(content: Record<string, unknown>) {
+    fs.writeFileSync(path.join(testDir, 'package.json'), JSON.stringify(content, null, 2));
+  }
+
+  describe('validatePackageJson', () => {
+    it('returns valid when package.json exists', () => {
+      writePackageJson({ name: 'test' });
+      const result = validatePackageJson(testDir);
+      expect(result.valid).toBe(true);
+    });
+
+    it('returns invalid when package.json is absent', () => {
+      const result = validatePackageJson(testDir);
+      expect(result.valid).toBe(false);
+      expect(result.fixCommand).toBeDefined();
+    });
+  });
+
+  describe('validateReactProject', () => {
+    it('returns valid when react is in dependencies', () => {
+      writePackageJson({ dependencies: { react: '^18.0.0' } });
+      const result = validateReactProject(testDir);
+      expect(result.valid).toBe(true);
+    });
+
+    it('returns valid when react is in devDependencies', () => {
+      writePackageJson({ devDependencies: { react: '^18.0.0' } });
+      const result = validateReactProject(testDir);
+      expect(result.valid).toBe(true);
+    });
+
+    it('returns invalid when react is not present', () => {
+      writePackageJson({ dependencies: {} });
+      const result = validateReactProject(testDir);
+      expect(result.valid).toBe(false);
+    });
+
+    it('returns invalid when package.json is absent', () => {
+      const result = validateReactProject(testDir);
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe('detectNextJs', () => {
+    it('returns true when next is in dependencies', () => {
+      writePackageJson({ dependencies: { next: '^14.0.0', react: '^18.0.0' } });
+      expect(detectNextJs(testDir)).toBe(true);
+    });
+
+    it('returns true when next is in devDependencies', () => {
+      writePackageJson({ devDependencies: { next: '^14.0.0' } });
+      expect(detectNextJs(testDir)).toBe(true);
+    });
+
+    it('returns false for a plain React project without next', () => {
+      writePackageJson({ dependencies: { react: '^18.0.0' } });
+      expect(detectNextJs(testDir)).toBe(false);
+    });
+
+    it('returns false when package.json is absent', () => {
+      expect(detectNextJs(testDir)).toBe(false);
+    });
+
+    it('returns false when dependencies are empty', () => {
+      writePackageJson({ dependencies: {} });
+      expect(detectNextJs(testDir)).toBe(false);
+    });
+  });
+});

packages/cli/src/utils/environment-validator.ts

@@ -63,6 +63,26 @@ export function validateReactProject(cwd: string = process.cwd()): EnvironmentVa
   }
 }
 
+/**
+ * Check if this is a Next.js project (has next in dependencies).
+ */
+export function detectNextJs(cwd: string = process.cwd()): boolean {
+  const pkgPath = path.join(cwd, 'package.json');
+
+  if (!checkFileExists(pkgPath)) return false;
+
+  try {
+    const pkg = readJsonFile(pkgPath) as Record<string, unknown>;
+    const deps = {
+      ...(pkg.dependencies as Record<string, string> | undefined),
+      ...(pkg.devDependencies as Record<string, string> | undefined),
+    };
+    return 'next' in deps;
+  } catch {
+    return false;
+  }
+}
+
 export function validateEnvironment(cwd: string = process.cwd()): EnvironmentCheckResult {
   return {
     hasPackageJson: validatePackageJson(cwd),