Merge pull request #5 from d2verb/feat/simpler-serve

simplify serve()

Author: d2verb

README.md

@@ -25,6 +25,7 @@ deno run -A page.tsx
 ```tsx
 /** @jsxImportSource https://esm.sh/preact@10 */
 import { useEffect, useState } from "https://esm.sh/preact@10/hooks";
+import { serve } from "https://esm.sh/jsr/@d2verb/pera";
 
 type Props = { initial?: number };
 
@@ -65,21 +66,17 @@ export function App({ initial = 0 }: Props) {
   );
 }
 
-if (import.meta.main) {
-  const { serve } = await import("jsr:@d2verb/pera");
-
-  await serve({
-    port: 8080,
-    title: "Counter Sample",
-    moduleUrl: import.meta.url,
-    props: { initial: 4 },
-    api: {
-      "/students/:name": {
-        GET: (_, ctx) => new Response(`Hello, ${ctx.params.name}!`),
-      },
+await serve({
+  port: 8080,
+  title: "Counter Sample",
+  moduleUrl: import.meta.url,
+  props: { initial: 4 },
+  api: {
+    "/students/:name": {
+      GET: (_, ctx) => new Response(`Hello, ${ctx.params.name}!`),
     },
-  });
-}
+  },
+});
 ```
 
 Open your browser at http://localhost:8080 and see your Preact app running.

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@d2verb/pera",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts",

examples/counter.tsx

@@ -1,5 +1,6 @@
 /** @jsxImportSource https://esm.sh/preact@10 */
 import { useEffect, useState } from "https://esm.sh/preact@10/hooks";
+import { serve } from "https://esm.sh/jsr/@d2verb/pera";
 
 type Props = { initial?: number };
 
@@ -40,18 +41,14 @@ export function App({ initial = 0 }: Props) {
   );
 }
 
-if (import.meta.main) {
-  const { serve } = await import("jsr:@d2verb/pera");
-
-  await serve({
-    port: 8080,
-    title: "Counter Sample",
-    moduleUrl: import.meta.url,
-    props: { initial: 4 },
-    api: {
-      "/students/:name": {
-        GET: (_, ctx) => new Response(`Hello, ${ctx.params.name}!`),
-      },
+await serve({
+  port: 8080,
+  title: "Counter Sample",
+  moduleUrl: import.meta.url,
+  props: { initial: 4 },
+  api: {
+    "/students/:name": {
+      GET: (_, ctx) => new Response(`Hello, ${ctx.params.name}!`),
     },
-  });
-}
+  },
+});

src/cli.ts

@@ -40,6 +40,7 @@ if (args.length === 0 || args[0] !== "new" || args.length > 2) {
 const path = args.length === 2 ? args[1] : "app.tsx";
 const content = `/** @jsxImportSource https://esm.sh/preact@10 */
 import { useState } from "https://esm.sh/preact@10/hooks";
+import { serve } from "https://esm.sh/jsr/@d2verb/pera";
 
 export function App() {
   const [counter, setCounter] = useState(0);
@@ -53,15 +54,12 @@ export function App() {
   );
 }
 
-if (import.meta.main) {
-  const { serve } = await import("jsr:@d2verb/pera");
-
-  await serve({
-    port: 8080,
-    title: "Counter",
-    moduleUrl: import.meta.url,
-  });
-}`;
+await serve({
+  port: 8080,
+  title: "Counter",
+  moduleUrl: import.meta.url,
+});
+`;
 
 if (await fileExists(path)) {
   console.error(`File ${path} already exists`);

src/mod.ts

@@ -6,11 +6,48 @@
  * @module
  */
 
-export * from "./server.ts";
+import type { PeraOptions } from "./types.ts";
+
+/**
+ * Serve the Pera app. serve() implicitly treats a component named App as
+ * the root component. Therefore, you must define a component named App.
+ *
+ * @example Basic Example
+ * ```ts
+ * await serve({
+ *   port: 8080,
+ *   moduleUrl: import.meta.url, // This is required
+ * });
+ * ```
+ * 
+ * @example With API
+ * ```ts
+ * await serve({
+ *   port: 8080,
+ *   moduleUrl: import.meta.url,
+ *   api: {
+ *     // The actual path is `/_pera/api/students/:name`
+ *     "/students/:name": {
+ *       GET: (_, ctx) => new Response(`Hello, ${ctx.params.name}!`),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @param opts The options for the Pera app.
+ */
+export async function serve(opts: PeraOptions): Promise<void> {
+  if (typeof Deno === "undefined") return;
+
+  const { serveImpl } = await import("./server.ts");
+  return serveImpl(opts);
+}
+
 export type {
   ApiContext,
   ApiFn,
   ApiMap,
   ApiMethod,
   ApiMethodMap,
 } from "./api.ts";
+export type { PeraOptions };

src/server.ts

@@ -1,48 +1,14 @@
-import { type ApiMap, type ApiMethod, findEndpoint } from "./api.ts";
+import { type ApiMethod, findEndpoint } from "./api.ts";
 import { escapeHtml, filePathFromModuleUrl } from "./utils.ts";
+import type { PeraOptions } from "./types.ts";
 import { transpile } from "@deno/emit";
 
 /**
- * The options for the Pera app.
- */
-export type PeraOptions = {
-  /** The port to listen on. (Default: 8080) */
-  port?: number;
-  /** The title of the app. This value will be used as the title of the HTML document. (Default: "Pera App") */
-  title?: string;
-  /** The props to pass to the App component. (Default: {}) */
-  // deno-lint-ignore no-explicit-any
-  props?: Record<string, any>;
-  /** The URL of the module to import the App component from. */
-  moduleUrl: string;
-  /** The ID of the root element to render the App component into. (Default: "root") */
-  rootId?: string;
-  /** Whether to enable hot module replacement. (Default: true) */
-  hmr?: boolean;
-  /** The API endpoints to expose to the client. (Default: {}) */
-  api?: ApiMap;
-};
-
-/**
- * Serve the Pera app. serve() implicitly treats a component named App as
- * the root component. Therefore, you must define a component named App.
- *
- * @example Basic Example
- * ```ts
- * // Make sure to import the serve function in the main module.
- * if (import.meta.main) {
- *   const { serve } = await import("jsr:@d2verb/pera");
- *
- *   await serve({
- *     port: 8080,
- *     moduleUrl: import.meta.url,
- *   });
- * }
- * ```
+ * The implementation of the serve() function.
  *
  * @param opts The options for the Pera app.
  */
-export function serve(opts: PeraOptions) {
+export function serveImpl(opts: PeraOptions) {
   const port = opts.port ?? 8080;
   const title = opts.title ?? "Pera App";
   const rootId = opts.rootId ?? "root";

src/types.ts

@@ -0,0 +1,22 @@
+import type { ApiMap } from "./api.ts";
+
+/**
+ * The options for the Pera app.
+ */
+export type PeraOptions = {
+  /** The port to listen on. (Default: 8080) */
+  port?: number;
+  /** The title of the app. This value will be used as the title of the HTML document. (Default: "Pera App") */
+  title?: string;
+  /** The props to pass to the App component. (Default: {}) */
+  // deno-lint-ignore no-explicit-any
+  props?: Record<string, any>;
+  /** The URL of the module to import the App component from. */
+  moduleUrl: string;
+  /** The ID of the root element to render the App component into. (Default: "root") */
+  rootId?: string;
+  /** Whether to enable hot module replacement. (Default: true) */
+  hmr?: boolean;
+  /** The API endpoints to expose to the client. (Default: {}) */
+  api?: ApiMap;
+};