sdocs 0.0.26 → 0.0.28

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.28] - 2026-07-03
+
+### Changed
+
+- **`sdocs dev`/`run`/`build` no longer write a `.sdocs/` directory into the
+  project.** The generated app is staged in a unique directory under
+  `node_modules/.cache/` (imports resolve exactly as before) and removed on
+  exit. This also fixes `sdocs build` breaking a concurrently running dev
+  server — they previously shared the same staging directory.
+
+## [0.0.27] - 2026-07-03
+
+### Added
+
+- **`sdocs run`** — same as `dev`, built for `npx sdocs run`: works with no
+  local install. The dev server allows sdocs' own files from the npx cache,
+  and when the project has its own `svelte`, previews dedupe onto it, so
+  components and their dependencies always resolve from the project.
+
+### Changed
+
+- `sdocs build` applies the same svelte dedupe as the dev server.
+
 ## [0.0.26] - 2026-07-03
 
 ### Fixed

package/dist/commands/build.js

@@ -4,11 +4,12 @@ import { svelte } from '@sveltejs/vite-plugin-svelte';
 import { loadConfig } from '../server/config.js';
 import { sdocsPlugin } from '../vite.js';
 import { generateBuildFiles, cleanBuildFiles } from '../server/app-gen.js';
+import { svelteDedupe } from './dev.js';
 export async function buildCommand() {
     const cwd = process.cwd();
     const config = await loadConfig(cwd);
     console.log('[sdocs] Building static site...');
-    // Generate .sdocs/ with entry + preview HTML files
+    // Generate the staging directory (in the OS temp dir) with entry + preview HTML files
     const { sdocsDir, inputs } = await generateBuildFiles(config, cwd);
     const inputCount = Object.keys(inputs).length;
     console.log(`[sdocs] Generated ${inputCount} page(s) (1 main + ${inputCount - 1} previews)`);
@@ -18,6 +19,9 @@ export async function buildCommand() {
         await build({
             configFile: false,
             root: sdocsDir,
+            resolve: {
+                dedupe: svelteDedupe(cwd),
+            },
             plugins: [
                 svelte(),
                 sdocsPlugin({ ...config, include: absoluteIncludes, _buildMode: true }),
@@ -33,6 +37,6 @@ export async function buildCommand() {
         console.log(`[sdocs] Build complete → dist/`);
     }
     finally {
-        await cleanBuildFiles(cwd);
+        await cleanBuildFiles(sdocsDir);
     }
 }

package/dist/commands/dev.d.ts

@@ -1 +1,9 @@
+/** sdocs' own install location — under npx this is the npx cache, not the project */
+export declare function sdocsPackageRoot(): string;
+/**
+ * Prefer the project's own svelte over the copy next to sdocs when both exist
+ * (e.g. running via npx): previews import the project's components, and two
+ * svelte runtimes in one page don't mix.
+ */
+export declare function svelteDedupe(cwd: string): string[];
 export declare function devCommand(): Promise<void>;

package/dist/commands/dev.js

@@ -1,20 +1,45 @@
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 import { createServer } from 'vite';
 import { svelte } from '@sveltejs/vite-plugin-svelte';
 import { loadConfig } from '../server/config.js';
 import { sdocsPlugin } from '../vite.js';
 import { generateDevFiles, cleanBuildFiles } from '../server/app-gen.js';
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** sdocs' own install location — under npx this is the npx cache, not the project */
+export function sdocsPackageRoot() {
+    return resolve(__dirname, '../..');
+}
+/**
+ * Prefer the project's own svelte over the copy next to sdocs when both exist
+ * (e.g. running via npx): previews import the project's components, and two
+ * svelte runtimes in one page don't mix.
+ */
+export function svelteDedupe(cwd) {
+    try {
+        require.resolve('svelte/package.json', { paths: [cwd] });
+        return ['svelte'];
+    }
+    catch {
+        return [];
+    }
+}
 export async function devCommand() {
     const cwd = process.cwd();
     const config = await loadConfig(cwd);
     console.log('[sdocs] Starting dev server...');
-    // Generate .sdocs/ temp directory with entry files
+    // Generate the staging directory (in the OS temp dir) with entry files
     const sdocsDir = await generateDevFiles(config, cwd);
-    // Resolve include patterns to absolute paths (relative to cwd, not .sdocs/)
+    // Resolve include patterns to absolute paths (relative to cwd, not the staging dir)
     const absoluteIncludes = config.include.map((p) => resolve(cwd, p));
     const server = await createServer({
         configFile: false,
         root: sdocsDir,
+        resolve: {
+            dedupe: svelteDedupe(cwd),
+        },
         plugins: [
             svelte(),
             sdocsPlugin({ ...config, include: absoluteIncludes }),
@@ -23,7 +48,10 @@ export async function devCommand() {
             port: config.port,
             open: config.open,
             fs: {
-                allow: [cwd],
+                // The staging dir (an explicit allow list replaces Vite's implicit
+                // root allowance), the project, and sdocs' own dependency tree
+                // (the npx cache when running without a local install).
+                allow: [sdocsDir, cwd, resolve(sdocsPackageRoot(), '..')],
             },
         },
     });
@@ -32,7 +60,7 @@ export async function devCommand() {
     // Cleanup on exit
     const cleanup = async () => {
         await server.close();
-        await cleanBuildFiles(cwd);
+        await cleanBuildFiles(sdocsDir);
         process.exit(0);
     };
     process.on('SIGINT', cleanup);

package/dist/server/app-gen.d.ts

@@ -1,10 +1,10 @@
 import type { ResolvedSdocsConfig } from '../types.js';
-/** Generate .sdocs/ directory with entry files for dev mode */
+/** Generate the staging directory with entry files for dev mode */
 export declare function generateDevFiles(config: ResolvedSdocsConfig, cwd: string): Promise<string>;
-/** Generate .sdocs/ directory with entry + preview HTML files for build mode */
+/** Generate the staging directory with entry + preview HTML files for build mode */
 export declare function generateBuildFiles(config: ResolvedSdocsConfig, cwd: string): Promise<{
     sdocsDir: string;
     inputs: Record<string, string>;
 }>;
-/** Remove the .sdocs/ temp directory */
-export declare function cleanBuildFiles(cwd: string): Promise<void>;
+/** Remove a staging directory created by generateDevFiles/generateBuildFiles */
+export declare function cleanBuildFiles(stagingDir: string): Promise<void>;

package/dist/server/app-gen.js

@@ -1,4 +1,6 @@
-import { mkdir, writeFile, rm, readFile, copyFile, readdir } from 'node:fs/promises';
+import { mkdir, mkdtemp, writeFile, rm, readFile, copyFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { dirname, resolve, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { discoverDocFiles, getSdocKind } from './discovery.js';
@@ -14,6 +16,36 @@ async function copyClientApp(sdocsDir) {
     await copyDir(getClientSourceDir(), resolve(sdocsDir, 'client'));
     await copyDir(resolve(__dirname, '../ui'), resolve(sdocsDir, 'ui'));
 }
+/** Nearest node_modules walking up from dir (mirrors Node's resolution) */
+function findNearestNodeModules(dir) {
+    let current = resolve(dir);
+    for (;;) {
+        const candidate = join(current, 'node_modules');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * Create a unique staging directory for the generated app. It lives inside
+ * node_modules/.cache — never a tracked file in the user's project — and being
+ * physically inside node_modules keeps the full walk-up resolution chain for
+ * bare imports (svelte, ...) intact, including hoisted monorepo setups. When
+ * no node_modules exists anywhere (running via npx in a bare folder), sdocs'
+ * own tree provides one; the OS temp dir is the last resort.
+ */
+async function createStagingDir(cwd) {
+    const nodeModules = findNearestNodeModules(cwd) ?? findNearestNodeModules(resolve(__dirname, '..'));
+    if (nodeModules) {
+        const cacheDir = join(nodeModules, '.cache');
+        await mkdir(cacheDir, { recursive: true });
+        return mkdtemp(join(cacheDir, 'sdocs-'));
+    }
+    return mkdtemp(join(tmpdir(), 'sdocs-'));
+}
 /** Copy a directory recursively */
 async function copyDir(src, dest) {
     await mkdir(dest, { recursive: true });
@@ -129,21 +161,19 @@ async function discoverSnippets(config, cwd) {
     }
     return results;
 }
-/** Generate .sdocs/ directory with entry files for dev mode */
+/** Generate the staging directory with entry files for dev mode */
 export async function generateDevFiles(config, cwd) {
-    const sdocsDir = resolve(cwd, '.sdocs');
-    await mkdir(sdocsDir, { recursive: true });
-    // Copy client components into .sdocs/client/ so they're compiled outside node_modules
+    const sdocsDir = await createStagingDir(cwd);
+    // Copy client components into the staging dir so they're compiled outside node_modules
     await copyClientApp(sdocsDir);
     await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.logo));
     await writeFile(resolve(sdocsDir, 'entry.js'), generateEntryJs(config));
     return sdocsDir;
 }
-/** Generate .sdocs/ directory with entry + preview HTML files for build mode */
+/** Generate the staging directory with entry + preview HTML files for build mode */
 export async function generateBuildFiles(config, cwd) {
-    const sdocsDir = resolve(cwd, '.sdocs');
-    await mkdir(sdocsDir, { recursive: true });
-    // Copy client components into .sdocs/client/
+    const sdocsDir = await createStagingDir(cwd);
+    // Copy client components into the staging dir
     await copyClientApp(sdocsDir);
     await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.logo));
     await writeFile(resolve(sdocsDir, 'entry.js'), generateEntryJs(config));
@@ -166,8 +196,7 @@ export async function generateBuildFiles(config, cwd) {
     }
     return { sdocsDir, inputs };
 }
-/** Remove the .sdocs/ temp directory */
-export async function cleanBuildFiles(cwd) {
-    const sdocsDir = resolve(cwd, '.sdocs');
-    await rm(sdocsDir, { recursive: true, force: true });
+/** Remove a staging directory created by generateDevFiles/generateBuildFiles */
+export async function cleanBuildFiles(stagingDir) {
+    await rm(stagingDir, { recursive: true, force: true });
 }

package/dist/server/cli.js

@@ -18,7 +18,8 @@ Usage:
   sdocs <command>
 
 Commands:
-  dev       Start development server with HMR
+  dev       Start development server with live reload
+  run       Same as dev — works with npx and no local install
   build     Build static documentation site
   preview   Serve built site locally
   init      Scaffold sdocs.config.js
@@ -39,7 +40,8 @@ async function main() {
         return;
     }
     switch (command) {
-        case 'dev': {
+        case 'dev':
+        case 'run': {
             const { devCommand } = await import('../commands/dev.js');
             await devCommand();
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdocs",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "description": "A lightweight documentation tool for Svelte 5 components",
   "type": "module",
   "license": "MIT",