@solidjs/start 1.2.0 → 2.0.0-alpha.0

package/scripts/validate-imports.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+
+/**
+ * Import Extension Validation Script for SolidStart
+ *
+ * This script validates that all relative imports in the src/ directory have
+ * explicit file extensions, which is mandated by Node.js ESM (ES Modules).
+ *
+ * Node.js requires explicit file extensions for relative imports when using
+ * ES modules to avoid ambiguity and improve performance. This script ensures
+ * compliance with this requirement.
+ *
+ * Features:
+ * - Scans all .ts and .tsx files in the src/ directory recursively
+ * - Detects relative imports (starting with ./ or ../) without extensions
+ * - Prevents .js/.jsx imports in TypeScript files (should use .ts/.tsx)
+ * - Ignores commented code, CSS imports, and dynamic imports (handled by bundlers)
+ * - Provides detailed error reporting with line numbers and suggestions
+ * - Exits with appropriate status codes for CI/CD integration
+ *
+ * Usage:
+ *   npm run validate-imports
+ *
+ * Exit codes:
+ *   0 - All relative imports have valid extensions
+ *   1 - Found relative imports without extensions
+ *
+ * Valid extensions for TypeScript files: .ts, .tsx, .json
+ * Invalid extensions for TypeScript files: .js, .jsx (use .ts/.tsx instead)
+ *
+ * @example
+ * // ❌ Invalid - missing extension
+ * import { config } from "./config/index";
+ *
+ * // ❌ Invalid - .js extension in TypeScript file
+ * import { config } from "./config/index.js";
+ *
+ * // ✅ Valid - has .ts extension
+ * import { config } from "./config/index.ts";
+ *
+ * // ✅ Valid - external package import (no extension needed)
+ * import { something } from "external-package";
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, extname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Configuration
+const SRC_DIR = join(__dirname, "..", "src");
+const VALID_EXTENSIONS = [".ts", ".tsx", ".json"];
+const INVALID_EXTENSIONS = [".js", ".jsx"];
+const FILE_EXTENSIONS = [".ts", ".tsx"];
+
+/**
+ * Recursively find all files with specified extensions
+ */
+function findFiles(dir, extensions, files = []) {
+  try {
+    const entries = readdirSync(dir);
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry);
+      const stat = statSync(fullPath);
+
+      if (stat.isDirectory()) {
+        findFiles(fullPath, extensions, files);
+      } else if (extensions.includes(extname(entry))) {
+        files.push(fullPath);
+      }
+    }
+  } catch (error) {
+    console.error(`Error reading directory ${dir}: ${error.message}`);
+  }
+
+  return files;
+}
+
+/**
+ * Check if a path is a relative import (starts with . or ..)
+ */
+function isRelativeImport(path) {
+  return path.startsWith("./") || path.startsWith("../");
+}
+
+/**
+ * Check if an import path has a valid file extension
+ */
+function hasValidExtension(path) {
+  return VALID_EXTENSIONS.some(ext => path.endsWith(ext));
+}
+
+/**
+ * Check if an import path has an invalid extension for TypeScript files
+ */
+function hasInvalidExtension(path) {
+  return INVALID_EXTENSIONS.some(ext => path.endsWith(ext));
+}
+
+/**
+ * Extract import/export statements from file content
+ * Matches both import and export statements with from clauses
+ */
+function extractImportExportStatements(content, filePath) {
+  const statements = [];
+  const lines = content.split("\n");
+
+  // Regex patterns for different import/export statements
+  const patterns = [
+    // Standard imports: import { ... } from '...'
+    /import\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+)?['"`]([^'"`]+)['"`]/g,
+    // Export from: export { ... } from '...'
+    /export\s+(?:\{[^}]*\}|\*)\s+from\s+['"`]([^'"`]+)['"`]/g,
+    // Export default from: export { default } from '...'
+    /export\s+\{\s*default\s*\}\s+from\s+['"`]([^'"`]+)['"`]/g
+    // Note: Dynamic imports are excluded as they're handled by bundlers
+  ];
+
+  lines.forEach((line, lineNumber) => {
+    const trimmedLine = line.trim();
+
+    // Skip commented lines, dynamic imports, and TypeScript type-only imports in d.ts files
+    if (
+      trimmedLine.startsWith("//") ||
+      trimmedLine.startsWith("/*") ||
+      trimmedLine.startsWith("*") ||
+      (filePath.endsWith(".d.ts") && trimmedLine.includes("import(")) ||
+      // Skip CSS imports as they're handled by bundlers
+      /import\s+['"`][^'"`]*\.css['"`]/.test(trimmedLine) ||
+      // Skip dynamic imports as they're handled by bundlers
+      /import\s*\(\s*['"`]/.test(trimmedLine)
+    ) {
+      return;
+    }
+
+    patterns.forEach(pattern => {
+      let match;
+      // Reset regex lastIndex to avoid issues with global flag
+      pattern.lastIndex = 0;
+      while ((match = pattern.exec(line)) !== null) {
+        const importPath = match[1];
+        if (importPath) {
+          statements.push({
+            path: importPath,
+            line: lineNumber + 1,
+            fullLine: line.trim(),
+            filePath
+          });
+        }
+      }
+    });
+  });
+
+  return statements;
+}
+
+/**
+ * Validate a single file for relative imports without extensions
+ */
+function validateFile(filePath) {
+  const errors = [];
+
+  try {
+    const content = readFileSync(filePath, "utf8");
+    const statements = extractImportExportStatements(content, filePath);
+
+    statements.forEach(statement => {
+      if (isRelativeImport(statement.path)) {
+        if (hasInvalidExtension(statement.path)) {
+          errors.push({
+            file: filePath,
+            line: statement.line,
+            importPath: statement.path,
+            fullLine: statement.fullLine,
+            type: "invalid-extension"
+          });
+        } else if (!hasValidExtension(statement.path)) {
+          errors.push({
+            file: filePath,
+            line: statement.line,
+            importPath: statement.path,
+            fullLine: statement.fullLine,
+            type: "missing-extension"
+          });
+        }
+      }
+    });
+  } catch (error) {
+    console.error(`Error reading file ${filePath}: ${error.message}`);
+  }
+
+  return errors;
+}
+
+/**
+ * Main validation function
+ */
+function validateImports() {
+  console.log("🔍 Validating relative imports in src/ directory...\n");
+
+  // Find all TypeScript/TSX files in src directory
+  const files = findFiles(SRC_DIR, FILE_EXTENSIONS);
+
+  if (files.length === 0) {
+    console.log("⚠️  No TypeScript files found in src/ directory");
+    process.exit(0);
+  }
+
+  console.log(`📁 Scanning ${files.length} files...\n`);
+
+  let totalErrors = 0;
+  const errorsByFile = new Map();
+
+  // Validate each file
+  files.forEach(file => {
+    const errors = validateFile(file);
+    if (errors.length > 0) {
+      errorsByFile.set(file, errors);
+      totalErrors += errors.length;
+    }
+  });
+
+  // Report results
+  if (totalErrors === 0) {
+    console.log("✅ All relative imports have valid extensions!");
+    process.exit(0);
+  } else {
+    const missingExtensionErrors = [];
+    const invalidExtensionErrors = [];
+
+    errorsByFile.forEach(errors => {
+      errors.forEach(error => {
+        if (error.type === "missing-extension") {
+          missingExtensionErrors.push(error);
+        } else if (error.type === "invalid-extension") {
+          invalidExtensionErrors.push(error);
+        }
+      });
+    });
+
+    if (missingExtensionErrors.length > 0) {
+      console.log(
+        `❌ Found ${missingExtensionErrors.length} relative import(s) without extensions:\n`
+      );
+
+      const missingByFile = new Map();
+      missingExtensionErrors.forEach(error => {
+        if (!missingByFile.has(error.file)) {
+          missingByFile.set(error.file, []);
+        }
+        missingByFile.get(error.file).push(error);
+      });
+
+      missingByFile.forEach((errors, file) => {
+        const relativePath = file.replace(process.cwd(), "").replace(/^\//, "");
+        console.log(`📄 ${relativePath}:`);
+
+        errors.forEach(error => {
+          console.log(`  Line ${error.line}: ${error.importPath}`);
+          console.log(`    ${error.fullLine}`);
+          console.log(
+            `    ${"".padStart(error.fullLine.indexOf(error.importPath), " ")}${"".padStart(error.importPath.length, "^")}`
+          );
+        });
+        console.log("");
+      });
+    }
+
+    if (invalidExtensionErrors.length > 0) {
+      console.log(
+        `❌ Found ${invalidExtensionErrors.length} relative import(s) with invalid extensions:\n`
+      );
+
+      const invalidByFile = new Map();
+      invalidExtensionErrors.forEach(error => {
+        if (!invalidByFile.has(error.file)) {
+          invalidByFile.set(error.file, []);
+        }
+        invalidByFile.get(error.file).push(error);
+      });
+
+      invalidByFile.forEach((errors, file) => {
+        const relativePath = file.replace(process.cwd(), "").replace(/^\//, "");
+        console.log(`📄 ${relativePath}:`);
+
+        errors.forEach(error => {
+          console.log(`  Line ${error.line}: ${error.importPath}`);
+          console.log(`    ${error.fullLine}`);
+          console.log(
+            `    ${"".padStart(error.fullLine.indexOf(error.importPath), " ")}${"".padStart(error.importPath.length, "^")}`
+          );
+        });
+        console.log("");
+      });
+    }
+
+    console.log("💡 Tips:");
+    if (missingExtensionErrors.length > 0) {
+      console.log('  - Add file extensions to relative imports (e.g., "./file" → "./file.ts")');
+    }
+    if (invalidExtensionErrors.length > 0) {
+      console.log("  - Replace .js/.jsx with .ts/.tsx in TypeScript files");
+    }
+    console.log("  - This is required by Node.js ESM modules");
+    console.log("  - Valid extensions for TypeScript files: " + VALID_EXTENSIONS.join(", "));
+    console.log("  - Invalid extensions for TypeScript files: " + INVALID_EXTENSIONS.join(", "));
+
+    process.exit(1);
+  }
+}
+
+// Run the validation
+validateImports();

package/src/client/StartClient.tsx

@@ -0,0 +1,34 @@
+// @refresh skip
+import App from "solid-start:app";
+import type { JSX } from "solid-js";
+import { ErrorBoundary } from "../shared/ErrorBoundary.tsx";
+
+function Dummy(props: { children: JSX.Element }) {
+  return props.children;
+}
+
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/client/start-client
+ */
+export function StartClient() {
+  return (
+    <Dummy>
+      <Dummy>
+        <ErrorBoundary>
+          <App />
+        </ErrorBoundary>
+      </Dummy>
+    </Dummy>
+  );
+}
+
+export function StartClientTanstack() {
+  return (
+    <Dummy>
+      <ErrorBoundary>
+        <App />
+      </ErrorBoundary>
+    </Dummy>
+  );
+}

package/src/client/index.tsx

@@ -0,0 +1,2 @@
+export { mount } from "./mount.ts";
+export { StartClient, StartClientTanstack } from "./StartClient.tsx";

package/src/client/mount.ts

@@ -0,0 +1,114 @@
+import type { JSX } from "solid-js";
+import { createStore } from "solid-js/store";
+import {
+  createComponent,
+  getHydrationKey,
+  getOwner,
+  hydrate,
+  type MountableElement
+} from "solid-js/web";
+
+/**
+ *
+ * Read more: https://docs.solidjs.com/solid-start/reference/client/mount
+ */
+export function mount(fn: () => JSX.Element, el: MountableElement) {
+  if (import.meta.env.START_ISLANDS) {
+    const map = new WeakMap();
+    async function mountIsland(el: HTMLElement) {
+      if (el.dataset.css) {
+        let css = JSON.parse(el.dataset.css);
+        for (let href of css) {
+          if (!document.querySelector(`link[href="${href}"]`)) {
+            let link = document.createElement("link");
+            link.rel = "stylesheet";
+            link.href = href;
+            document.head.appendChild(link);
+          }
+        }
+      }
+
+      let mod = await import(
+        /* @vite-ignore */
+        import.meta.env.MANIFEST["client"]!.chunks[el.dataset.id!.split("#")[0] as string]!.output
+          .path
+      );
+      if (!mod || !el.dataset.hk) return;
+
+      let Component = mod[el.dataset.id!.split("#")[1] as string];
+      let hk = el.dataset.hk;
+      // _$DEBUG("hydrating island", el.dataset.island, hk.slice(0, hk.length - 1) + `1-`, el);
+
+      let props = createStore({
+        ...JSON.parse(el.dataset.props!),
+        get children() {
+          const p = el.getElementsByTagName("solid-children");
+          getHydrationKey();
+          [...p].forEach(a => {
+            (a as any).__$owner = getOwner();
+          });
+          return;
+        }
+      });
+
+      map.set(el, props);
+
+      hydrate(() => createComponent(Component, props[0]), el, {
+        renderId: hk.slice(0, hk.length - 1) + `${1 + Number(el.dataset.offset)}-`,
+        owner: lookupOwner(el)
+      });
+
+      delete el.dataset.hk;
+      el.dataset.hkk = hk;
+    }
+
+    let queue: HTMLElement[] = [];
+    let queued = false;
+    function runTaskQueue(info: any) {
+      while (info.timeRemaining() > 0 && queue.length) {
+        mountIsland(queue.shift()!);
+      }
+      if (queue.length) {
+        requestIdleCallback(runTaskQueue);
+      } else queued = false;
+    }
+
+    const hydrateIslands = () => {
+      const islands: NodeListOf<HTMLElement> = document.querySelectorAll("solid-island[data-hk]");
+      const assets = new Set<string>();
+      islands.forEach((el: HTMLElement) => el.dataset.id && assets.add(el.dataset.id));
+      Promise.all(
+        [...assets].map(
+          asset =>
+            import(
+              /* @vite-ignore */ import.meta.env.MANIFEST["client"]!.chunks[
+                asset.split("#")[0] as string
+              ]!.output.path
+            )
+        )
+      )
+        .then(() => {
+          islands.forEach((el: HTMLElement) => {
+            if (el.dataset.when === "idle" && "requestIdleCallback" in window) {
+              if (!queued) {
+                queued = true;
+                requestIdleCallback(runTaskQueue);
+              }
+              queue.push(el);
+            } else mountIsland(el as HTMLElement);
+          });
+        })
+        .catch(e => console.error(e));
+    };
+
+    function lookupOwner(el: HTMLElement) {
+      const parent = el.closest("solid-children");
+      return parent && (parent as any).__$owner;
+    }
+
+    hydrateIslands();
+
+    return;
+  }
+  return hydrate(fn, el);
+}

package/src/client/spa/index.tsx

@@ -0,0 +1,9 @@
+// @refresh skip
+import type { JSX } from "solid-js";
+import { render, type MountableElement } from "solid-js/web";
+
+export function mount(fn: () => JSX.Element, el: MountableElement) {
+  render(fn, el);
+}
+
+export { StartClient } from "../StartClient.tsx";

package/src/config/constants.ts

@@ -0,0 +1,19 @@
+export const DEFAULT_EXTENSIONS = ["js", "jsx", "ts", "tsx"];
+
+export const CLIENT_BASE_PATH = "_build";
+
+export const VIRTUAL_MODULES = {
+  clientViteManifest: "solid-start:client-vite-manifest",
+  getClientManifest: "solid-start:get-client-manifest",
+  getManifest: "solid-start:get-manifest",
+  middleware: "solid-start:middleware",
+  serverFnManifest: "solidstart:server-fn-manifest",
+  clientEntry: "solid-start:client-entry",
+  serverEntry: "solid-start:server-entry",
+  app: "solid-start:app"
+} as const;
+
+export const VITE_ENVIRONMENTS = {
+  client: "client",
+  server: "ssr"
+}

package/src/config/dev-server.ts

@@ -0,0 +1,149 @@
+import { NodeRequest, sendNodeResponse } from "srvx/node";
+import {
+	type Connect,
+	isRunnableDevEnvironment,
+	type PluginOption,
+	type ViteDevServer,
+} from "vite";
+import { VITE_ENVIRONMENTS } from "./constants.ts";
+
+export function devServer(): Array<PluginOption> {
+	return [
+		{
+			name: "solid-start-dev-server",
+			configureServer(viteDevServer) {
+				(globalThis as any).VITE_DEV_SERVER = viteDevServer;
+				return async () => {
+				  if (viteDevServer.config.server.middlewareMode) return
+
+					const serverEnv =
+						viteDevServer.environments[VITE_ENVIRONMENTS.server];
+
+					if (!serverEnv) throw new Error("Server environment not found");
+					if (
+						// do not check via `isFetchableDevEnvironment` since nitro does implement the `FetchableDevEnvironment` interface but not via inheritance (which this helper checks)
+						"dispatchFetch" in serverEnv
+					)
+						return;
+					// another plugin is controlling the dev server
+					if (!isRunnableDevEnvironment(serverEnv)) {
+            return;
+					}
+
+          globalThis.USING_SOLID_START_DEV_SERVER = true;
+
+					removeHtmlMiddlewares(viteDevServer);
+
+					viteDevServer.middlewares.use(async (req, res) => {
+						if (req.originalUrl) {
+							req.url = req.originalUrl;
+						}
+						const webReq = new NodeRequest({ req, res });
+
+						try {
+							const serverEntry: {
+								default: { fetch: (req: Request) => Promise<Response> };
+							} = await serverEnv.runner.import("./src/entry-server.tsx");
+
+							const webRes = await serverEntry.default.fetch(webReq);
+
+							return sendNodeResponse(res, webRes);
+						} catch (e: unknown) {
+							console.error(e);
+							viteDevServer.ssrFixStacktrace(e as Error);
+
+							if (
+								webReq.headers.get("content-type")?.includes("application/json")
+							) {
+								return sendNodeResponse(
+									res,
+									Response.json(
+										{
+											status: 500,
+											error: "Internal Server Error",
+											message:
+												"An unexpected error occurred. Please try again later.",
+											timestamp: new Date().toISOString(),
+										},
+										{
+											status: 500,
+											headers: {
+												"Content-Type": "application/json",
+											},
+										},
+									),
+								);
+							}
+
+							return sendNodeResponse(
+								res,
+								new Response(
+									`
+                    <!DOCTYPE html>
+                    <html lang="en">
+                      <head>
+                        <meta charset="UTF-8" />
+                        <title>Error</title>
+                        <script type="module">
+                          import { ErrorOverlay } from '/@vite/client'
+                          document.body.appendChild(new ErrorOverlay(${JSON.stringify(
+														prepareError(req, e),
+													).replace(/</g, "\\u003c")}))
+                        </script>
+                      </head>
+                      <body>
+                      </body>
+                    </html>
+                  `,
+									{
+										status: 500,
+										headers: { "Content-Type": "text/html" },
+									},
+								),
+							);
+						}
+					});
+				};
+			},
+		},
+	];
+}
+
+/**
+ * Removes Vite internal middleware
+ *
+ * @param server
+ */
+function removeHtmlMiddlewares(server: ViteDevServer) {
+	const html_middlewares = [
+		"viteIndexHtmlMiddleware",
+		"vite404Middleware",
+		"viteSpaFallbackMiddleware",
+	];
+	for (let i = server.middlewares.stack.length - 1; i > 0; i--) {
+		if (
+			html_middlewares.includes(
+				// @ts-expect-error
+				server.middlewares.stack[i].handle.name,
+			)
+		) {
+			server.middlewares.stack.splice(i, 1);
+		}
+	}
+}
+
+/**
+ * Formats error for SSR message in error overlay
+ * @param req
+ * @param error
+ * @returns
+ */
+function prepareError(req: Connect.IncomingMessage, error: unknown) {
+	const e = error as Error;
+	return {
+		message: `An error occured while server rendering ${req.url}:\n\n\t${
+			typeof e === "string" ? e : e.message
+		} `,
+		stack: typeof e === "string" ? "" : e.stack,
+	};
+}