@t8/serve 0.1.19 → 0.1.21

package/README.md

@@ -1,6 +1,10 @@
 # @t8/serve
 
-Simple static file server + bundler, primarily for tests, manual or automated
+Simple static file server + bundler, primarily for demo apps and tests, manual or automated
+
+Use cases:
+- Use the CLI-based server to launch a demo or test app with a single CLI command.
+- Use the code-based setup to launch an own server from multiple tests, each with its own app.
 
 ## CLI
 
@@ -19,7 +23,7 @@ npx @t8/serve 3000 app public dist -b src/index.ts
 ```
 
 <details>
-<summary>Example</summary>
+<summary>Example 1 (flat)</summary>
 
 ```
 // package.json
@@ -32,7 +36,8 @@ npx @t8/serve 3000 app public dist -b src/index.ts
 /playground
   - index.css
   - index.html
-     + <script src="/dist/index.js"></script>
+      contains <script src="/dist/index.js"></script>
+      contains <link rel="stylesheet" href="/index.css"></script>
   - index.ts
 ```
 
@@ -54,6 +59,46 @@ webServer: {
 
 </details>
 
+<details>
+<summary>Example 2 (nested)</summary>
+
+```
+// package.json
+"scripts": {
+  "play": "npx @t8/serve 3000 * playground -b src/index.tsx"
+}
+```
+
+```
+/playground
+  src
+    - App.tsx
+    - index.css
+    - index.tsx // imports "./App.tsx", "./index.css"
+  - index.html
+      contains <script src="/dist/index.js"></script>
+      contains <link rel="stylesheet" href="/dist/index.css"></script>
+```
+
+```sh
+npm run play
+```
+
+```
+// With Playwright:
+// playwright.config.ts
+...
+use: {
+  baseURL: "http://localhost:3000",
+},
+webServer: {
+  command: "npm run play",
+  url: "http://localhost:3000",
+},
+```
+
+</details>
+
 ## Code
 
 ```ts
@@ -63,8 +108,8 @@ import { serve } from "@t8/serve";
 let server = await serve({
   port: 3000,
   path: "app",
+  bundle: true, // or input path, or `{ input, output, dir }`
   spa: true,
-  bundle: true,
 });
 
 // Stop
@@ -72,28 +117,66 @@ server.close();
 ```
 
 <details>
-<summary>Example</summary>
+<summary>Example 1 (flat)</summary>
 
 ```
 /playground
   - index.css
   - index.html
-     + <script src="/dist/index.js"></script>
+      contains <script src="/dist/index.js"></script>
+      contains <link rel="stylesheet" href="/index.css"></script>
   - index.ts
 ```
 
 ```ts
 // x.test.ts
 import { test } from "@playwright/test";
-import { serve, type Server } from "@t8/serve";
+import { type Server, serve } from "@t8/serve";
 
 let server: Server;
 
 test.beforeAll(async () => {
   server = await serve({
     path: "playground",
-    spa: true,
     bundle: true,
+    spa: true,
+  });
+});
+
+test.afterAll(() => {
+  server.close();
+});
+```
+
+</details>
+
+<details>
+<summary>Example 2 (nested)</summary>
+
+```
+/tests/x
+  src
+    - index.css
+    - index.tsx // imports "./App.tsx", "./index.css"
+  - index.html
+      contains <script src="/dist/index.js"></script>
+      contains <link rel="stylesheet" href="/dist/index.css"></script>
+  - index.ts
+  - index.test.ts
+```
+
+```ts
+// tests/x/index.test.ts
+import { test } from "@playwright/test";
+import { serve, type Server } from "@t8/serve";
+
+let server: Server;
+
+test.beforeAll(async () => {
+  server = await serve({
+    path: "tests/x",
+    bundle: "src/index.tsx",
+    spa: true,
   });
 });
 

package/dist/index.js

@@ -16,9 +16,10 @@ async function bundle({ path = "", bundle: options } = {}) {
       input: options
     };
   else normalizedOptions = options;
+  let dir = normalizedOptions.dir ?? "dist";
   let inputFile = join(path, normalizedOptions.input ?? "index.ts");
-  let outputFile = join(path, "dist", normalizedOptions.output ?? "index.js");
-  await rm(join(path, "dist"), { recursive: true, force: true });
+  let outputFile = join(path, dir, normalizedOptions.output ?? "index.js");
+  await rm(join(path, dir), { recursive: true, force: true });
   await build({
     entryPoints: [inputFile],
     outfile: outputFile,

package/dist/run.cjs

@@ -19,9 +19,10 @@ async function bundle({ path = "", bundle: options } = {}) {
       input: options
     };
   else normalizedOptions = options;
+  let dir = normalizedOptions.dir ?? "dist";
   let inputFile = (0, import_node_path.join)(path, normalizedOptions.input ?? "index.ts");
-  let outputFile = (0, import_node_path.join)(path, "dist", normalizedOptions.output ?? "index.js");
-  await (0, import_promises.rm)((0, import_node_path.join)(path, "dist"), { recursive: true, force: true });
+  let outputFile = (0, import_node_path.join)(path, dir, normalizedOptions.output ?? "index.js");
+  await (0, import_promises.rm)((0, import_node_path.join)(path, dir), { recursive: true, force: true });
   await (0, import_esbuild.build)({
     entryPoints: [inputFile],
     outfile: outputFile,

package/dist/run.mjs

@@ -18,9 +18,10 @@ async function bundle({ path = "", bundle: options } = {}) {
       input: options
     };
   else normalizedOptions = options;
+  let dir = normalizedOptions.dir ?? "dist";
   let inputFile = join(path, normalizedOptions.input ?? "index.ts");
-  let outputFile = join(path, "dist", normalizedOptions.output ?? "index.js");
-  await rm(join(path, "dist"), { recursive: true, force: true });
+  let outputFile = join(path, dir, normalizedOptions.output ?? "index.js");
+  await rm(join(path, dir), { recursive: true, force: true });
   await build({
     entryPoints: [inputFile],
     outfile: outputFile,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@t8/serve",
-  "version": "0.1.19",
-  "description": "",
+  "version": "0.1.21",
+  "description": "Simple static file server + bundler, primarily for demo apps and tests, manual or automated",
   "keywords": [
     "node",
     "server",
@@ -20,7 +20,7 @@
   "main": "dist/index.js",
   "scripts": {
     "build": "npx npm-run-all clean -p compile compile-mjs-bin compile-cjs-bin",
-    "clean": "node -e \"require('node:fs').rmSync('dist', {force: true, recursive: true});\"",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { force: true, recursive: true });\"",
     "compile": "npx esbuild index.ts --bundle --outdir=dist --platform=node --format=esm --external:esbuild",
     "compile-mjs-bin": "npx esbuild src/run.ts --bundle --outfile=dist/run.mjs --platform=node --format=esm --external:esbuild",
     "compile-cjs-bin": "npx esbuild src/run.ts --bundle --outfile=dist/run.cjs --platform=node --format=cjs --external:esbuild",

package/src/BundleConfig.ts

@@ -1,4 +1,20 @@
 export type BundleConfig = {
+  /**
+   * Output directory path relative to the server config `path`.
+   *
+   * @defaultValue "dist"
+   */
+  dir?: string;
+  /**
+   * Input path relative to the server config `path`.
+   *
+   * @defaultValue "index.ts"
+   */
   input?: string;
+  /**
+   * Output path relative to the bundle config `dir`.
+   *
+   * @defaultValue "index.js"
+   */
   output?: string;
 };

package/src/Config.ts

@@ -1,12 +1,41 @@
 import type { BundleConfig } from "./BundleConfig";
 
 export type Config = {
+  /** Server URL. */
   url?: string;
+  /**
+   * Server host.
+   *
+   * @defaultValue "localhost"
+   */
   host?: string;
+  /**
+   * Server port.
+   *
+   * @defaultValue 3000
+   */
   port?: number;
+  /** Application path. */
   path?: string;
+  /**
+   * Public assets directories. If not provided, the application
+   * `path` is served as a public assets directory.
+   */
   dirs?: string[];
+  /**
+   * Enables single-page application (SPA) mode. If `true`, all
+   * unmatched URLs are served as "/".
+   */
   spa?: boolean;
+  /** Whether to log to the console. */
   log?: boolean;
-  bundle?: boolean | string | BundleConfig;
+  /**
+   * Bundle config.
+   *
+   * If `undefined`, bundling is skipped.
+   * Otherwise, its type is `BundleConfig`, with the following shorthand options:
+   * If `true`, it's equivalent to `{ input: "index.ts", output: "index.js" }`.
+   * If `string`, it's equivalent to `input` in `{ input, ouput: "index.js" }`.
+   */
+  bundle?: boolean | string | BundleConfig | undefined;
 };

package/src/bundle.ts

@@ -16,10 +16,11 @@ export async function bundle({ path = "", bundle: options }: Config = {}) {
     };
   else normalizedOptions = options;
 
+  let dir = normalizedOptions.dir ?? "dist";
   let inputFile = join(path, normalizedOptions.input ?? "index.ts");
-  let outputFile = join(path, "dist", normalizedOptions.output ?? "index.js");
+  let outputFile = join(path, dir, normalizedOptions.output ?? "index.js");
 
-  await rm(join(path, "dist"), { recursive: true, force: true });
+  await rm(join(path, dir), { recursive: true, force: true });
 
   await build({
     entryPoints: [inputFile],

package/src/isValidFilePath.ts

@@ -1,6 +1,7 @@
 import { access, lstat } from "node:fs/promises";
 
 export async function isValidFilePath(filePath: string, dirPath: string) {
+  // Disallow path traversal outside `dirPath`
   if (!filePath.startsWith(dirPath)) return false;
 
   try {