waku 0.19.0 → 0.19.2

package/README.md

@@ -15,7 +15,7 @@ visit [waku.gg](https://waku.gg) or `npm create waku@latest`
 
 **Waku** _(wah-ku)_ or **わく** means “framework” in Japanese. As the minimal React framework, it aims to accelerate the work of developers at startups and agencies building small to medium-sized React projects. These include marketing websites, light ecommerce, and web applications.
 
-We recommend other frameworks for heavy ecommerce or enterprise applications. Waku is a lightweight alternative designed to bring a fun developer experience to the modern React server components era. Yes, let’s make React development fun again!
+We recommend other frameworks for heavy ecommerce or enterprise applications. Waku is a lightweight alternative designed to bring a fun developer experience to the modern React server components era. Yes, let’s make React development fun!
 
 > Waku is in rapid development and some features are currently missing. Please try it on non-production projects and report any issues you may encounter. Expect that there will be some breaking changes on the road towards a stable v1 release. Contributors are welcome.
 
@@ -27,17 +27,29 @@ Start a new Waku project with the `create` command for your preferred package ma
 npm create waku@latest
 ```
 
+**Node.js version requirement:** `^20.8.0 || ^18.16.0`
+
 ## Rendering
 
-Let's face it: React is getting complicated. But not without good reason!
+While there's a bit of a learning curve to modern React rendering, it introduces powerful new patterns of composability that are only possible with the advent of React [server components](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md).
+
+So please don't be intimidated by the `'use client'` directive! Once you get the hang of it, you'll appreciate how awesome it is to flexibly move server-client boundaries with a single line of code as your full-stack React codebase evolves over time.
+
+And please don't fret about client components! Even if you only lightly optimize towards server components, your client bundle size will be smaller than traditional React frameworks, which are 100% client components.
+
+> Future versions of Waku may provide additional opt-in APIs to abstract some of the complexity away for an improved developer experience.
+
+#### Overview
 
-While there's a bit of a learning curve to modern React rendering, it introduces powerful new patterns of composability that are only made possible with the advent of React server components. So stick with us.
+Each layout and page in Waku is composed of a React component heirarchy.
 
-Future versions of Waku may provide additional APIs to abstract away some of the complexity for an improved developer experience.
+It begins with a server component at the top of the tree. Then at points down the heirarchy, you'll eventually import a component that needs client component APIs. Mark this file with a `'use client'` directive at the top. When imported into a server component, it will create a server-client boundary. Below this point all imported components are hydrated and will run in the browser as well.
+
+Server components can still be rendered below this boundary, but only via composition (e.g., `children` props).
 
 #### Server components
 
-Waku follows React conventions including support for [server components](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md) and [server actions](https://react.dev/reference/react/use-server). Server components can be made async to securely perform server-side logic and data fetching, but have no interactivity.
+Server components can be made async and can securely perform server-side logic and data fetching. Feel free to access the local file-system and import heavy dependencies since they aren't included in the client bundle. They have no state, interactivity, or access to browser APIs since they run exclusively on the server.
 
 ```tsx
 // server component
@@ -54,7 +66,7 @@ export const StorePage = async () => {
 
 #### Client components
 
-Client components are specified with the `'use client'` directive at the top of the file. They can use all traditional React features such as state, effects, and event handlers.
+A `'use client'` directive placed at the top of a file will create a server-client boundary when the module is imported into a server component. All components imported below the boundary will be hydrated to run in the browser as well. They can use all traditional React features such as state, effects, and event handlers.
 
 ```tsx
 // client component
@@ -74,13 +86,48 @@ export const Counter = () => {
 };
 ```
 
+#### Shared components
+
+Simple React components that [meet all of the rules](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md#sharing-code-between-server-and-client) of both server and client components can be imported into either server or client components without affecting the server-client boundary.
+
+```tsx
+// shared component
+export const Headline = ({ children }) => {
+  return <h3>{children}</h3>;
+};
+```
+
 #### Weaving patterns
 
-Server components can import client components and doing so will create a server-client boundary. Client components cannot import server components, but they can accept server components as props such as `children`.
+Server components can import client components and doing so will create a server-client boundary. Client components cannot import server components, but they can accept server components as props such as `children`. For example, you may want to add global context providers this way.
+
+```tsx
+// ./src/templates/root-layout.tsx
+import { Providers } from '../components/providers.js';
+
+export const RootLayout = async ({ children }) => {
+  return (
+    <Providers>
+      <main>{children}</main>
+    </Providers>
+  );
+};
+```
+
+```tsx
+// ./src/components/providers.tsx
+'use client';
+
+import { Provider } from 'jotai';
+
+export const Providers = ({ children }) => {
+  return <Provider>{children}</Provider>;
+};
+```
 
 #### Server-side rendering
 
-Waku provides static prerendering (SSG) or server-side rendering (SSR) options for layouts and pages including their server _and_ client components. Client components are then hydrated in the browser to support events, effects, and so on.
+Waku provides static prerendering (SSG) or server-side rendering (SSR) options for layouts and pages including both their server and client components.
 
 #### Further reading
 
@@ -90,7 +137,9 @@ To learn more about the modern React architecture, we recommend [Making Sense of
 
 The entry point for routing in Waku projects is `./src/entries.tsx`. Export the `createPages` function to create your layouts and pages programatically.
 
-Both `createLayout` and `createPage` accept a configuration object to specify the route path, React component, and render method (`'static'` for SSG or `'dynamic'` for SSR). Layout components must accept a `children` prop.
+Both `createLayout` and `createPage` accept a configuration object to specify the route path, React component, and render method. Waku currently supports two options: `'static'` for static prerendering (SSG) or `'dynamic'` for server-side rendering (SSR).
+
+For example, you can statically prerender a global header and footer in the root layout at build time, but dynamically render the rest of a home page at request time for personalized user experiences.
 
 ```tsx
 // ./src/entries.tsx
@@ -244,7 +293,9 @@ export default createPages(async ({ createPage }) => {
 
 #### Catch-all routes
 
-Catch-all or "wildcard" routes (e.g., `/app/[...catchAll]`) have indefinite segments. Wildcard routes receive a prop with segment values as an ordered array. For example, the `/app/profile/settings` route would receive a `catchAll` prop with the value `['profile', 'settings']`. These values can then be used to determine what to render in the component.
+Catch-all or "wildcard" routes (e.g., `/app/[...catchAll]`) have indefinite segments. Wildcard routes receive a prop with segment values as an ordered array.
+
+For example, the `/app/profile/settings` route would receive a `catchAll` prop with the value `['profile', 'settings']`. These values can then be used to determine what to render in the component.
 
 ```tsx
 // ./src/entries.tsx
@@ -323,7 +374,7 @@ export const Providers = ({ children }) => {
 
 #### Other layouts
 
-Layouts are also helpful further down the tree. For example you could add a layout at `path: '/blog` to add a sidebar to both the blog index and all blog article pages.
+Layouts are also helpful further down the tree. For example, you could add a layout at `path: '/blog'` to add a sidebar to both the blog index and all blog article pages.
 
 ```tsx
 // ./src/entries.tsx
@@ -347,10 +398,10 @@ import { Sidebar } from '../components/sidebar.js';
 
 export const BlogLayout = async ({ children }) => {
   return (
-    <>
+    <div className="flex">
       <div>{children}</div>
       <Sidebar />
-    </>
+    </div>
   );
 };
 ```
@@ -377,13 +428,13 @@ export const HomePage = async () => {
 
 Static assets such as images, fonts, stylesheets, and scripts can be placed in a special `./public` folder of the Waku project root directory. The public directory structure is served relative to the `/` base path.
 
-For example an image added to `./public/images/logo.svg` can be rendered via `<img src="/images/logo.svg" />`.
+For example, an image added to `./public/images/logo.svg` can be rendered via `<img src="/images/logo.svg" />`.
 
 ## Data fetching
 
 ### Server
 
-All of the wonderful patterns of React server components are supported. For example you can compile MDX files or perform code syntax highlighting on the server with zero impact on the client bundle size.
+All of the wonderful patterns of React server components are supported. For example, you can compile MDX files or perform code syntax highlighting on the server with zero impact on the client bundle size.
 
 ```tsx
 // ./src/templates/blog-article-page.tsx
@@ -395,8 +446,8 @@ export const BlogArticlePage = async ({ slug }) => {
 
   return (
     <>
-      <title>{article.frontmatter.title}</h3>
-      <h1>{article.frontmatter.title}</h3>
+      <title>{article.frontmatter.title}</title>
+      <h1>{article.frontmatter.title}</h1>
       <MDX>{article.content}</MDX>
     </>
   );
@@ -444,6 +495,35 @@ export const HomePage = async () => {
 };
 ```
 
+Metadata could also be generated programatically.
+
+```tsx
+// ./src/templates/home-page.tsx
+export const HomePage = async () => {
+  return (
+    <>
+      <Head />
+      <div>{/* ...*/}</div>
+    </>
+  );
+};
+
+const Head = async () => {
+  const metadata = await getMetadata();
+
+  return (
+    <>
+      <title>{metadata.title}</title>
+      <meta property="description" content={metadata.description} />
+    </>
+  );
+};
+
+const getMetadata = async () => {
+  /* ... */
+};
+```
+
 ## Styling
 
 ### Global styles
@@ -578,8 +658,23 @@ npx wrangler dev # or deploy
 
 ```
 npm run build -- --with-deno
-DENO_DEPLOY_TOKEN=... deployctl deploy --project=... --prod serve.ts --exclude node_modules
+DENO_DEPLOY_TOKEN=... deployctl deploy --project=... --prod dist/serve.js --exclude node_modules
+```
+
+### Netlify Deploy (experimental)
+
+```
+npm run build -- --with-netlify
+netlify deploy
+```
+
+### AWS Lambda (experimental)
+
 ```
+npm run build -- --with-aws-lambda
+```
+
+The handler entrypoint is `dist/serve.js` - see [Hono AWS Lambda Deploy Docs](https://hono.dev/getting-started/aws-lambda#_3-deploy)
 
 ## Community
 

package/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+// eslint-disable-next-line import/no-unresolved
+import './dist/cli.js';

package/dist/cli.d.ts

@@ -1,2 +1 @@
-#!/usr/bin/env node
 export {};

package/dist/cli.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 import path from 'node:path';
 import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
@@ -33,6 +32,15 @@ const { values, positionals } = parseArgs({
         'with-deno': {
             type: 'boolean'
         },
+        'with-netlify': {
+            type: 'boolean'
+        },
+        'with-netlify-static': {
+            type: 'boolean'
+        },
+        'with-aws-lambda': {
+            type: 'boolean'
+        },
         version: {
             type: 'boolean',
             short: 'v'
@@ -92,26 +100,22 @@ async function runBuild(options) {
         ...options,
         config,
         env: process.env,
-        vercel: values['with-vercel'] ?? !!process.env.VERCEL ? {
-            type: values['with-vercel-static'] ? 'static' : 'serverless'
-        } : undefined,
-        cloudflare: !!values['with-cloudflare'],
-        deno: !!values['with-deno']
+        deploy: (values['with-vercel'] ?? !!process.env.VERCEL ? values['with-vercel-static'] ? 'vercel-static' : 'vercel-serverless' : undefined) || (values['with-cloudflare'] ? 'cloudflare' : undefined) || (values['with-deno'] ? 'deno' : undefined) || (values['with-netlify'] ? values['with-netlify-static'] ? 'netlify-static' : 'netlify-functions' : undefined) || (values['with-aws-lambda'] ? 'aws-lambda' : undefined)
     });
 }
 async function runStart(options) {
     const { distDir, publicDir, entriesJs } = await resolveConfig(config);
-    const entries = import(pathToFileURL(path.resolve(distDir, entriesJs)).toString());
+    const loadEntries = ()=>import(pathToFileURL(path.resolve(distDir, entriesJs)).toString());
     const app = new Hono();
+    app.use('*', serveStatic({
+        root: path.join(distDir, publicDir)
+    }));
     app.use('*', honoPrdMiddleware({
         ...options,
         config,
-        entries,
+        loadEntries,
         env: process.env
     }));
-    app.use('*', serveStatic({
-        root: path.join(distDir, publicDir)
-    }));
     const port = parseInt(process.env.PORT || '8080', 10);
     startServer(app, port);
 }
@@ -145,6 +149,8 @@ Options:
   --with-vercel         Output for Vercel on build
   --with-cloudflare     Output for Cloudflare on build
   --with-deno           Output for Deno on build
+  --with-netlify        Output for Netlify on build
+  --with-aws-lambda     Output for AWS Lambda on build
   -v, --version         Display the version number
   -h, --help            Display this help message
 `);

package/dist/client.d.ts

@@ -5,11 +5,20 @@ declare global {
     }
 }
 type Elements = Promise<Record<string, ReactNode>>;
-export declare const fetchRSC: (input: string, searchParamsString: string, rerender: (fn: (prev: Elements) => Elements) => void) => Elements;
+type SetElements = (fn: (prev: Elements) => Elements) => void;
+type CacheEntry = [
+    input: string,
+    searchParamsString: string,
+    setElements: SetElements,
+    elements: Elements
+];
+declare const fetchCache: [CacheEntry?];
+export declare const fetchRSC: (input: string, searchParamsString: string, setElements: SetElements, cache?: [CacheEntry?]) => Elements;
 export declare const prefetchRSC: (input: string, searchParamsString: string) => void;
-export declare const Root: ({ initialInput, initialSearchParamsString, children, }: {
+export declare const Root: ({ initialInput, initialSearchParamsString, cache, children, }: {
     initialInput?: string;
     initialSearchParamsString?: string;
+    cache?: typeof fetchCache;
     children: ReactNode;
 }) => import("react").FunctionComponentElement<import("react").ProviderProps<(input: string, searchParams?: URLSearchParams) => void>>;
 export declare const useRefetch: () => (input: string, searchParams?: URLSearchParams) => void;

package/dist/client.js

@@ -1,6 +1,6 @@
 /// <reference types="react/canary" />
 'use client';
-import { cache, createContext, createElement, memo, use, useCallback, useState, startTransition } from 'react';
+import { createContext, createElement, memo, use, useCallback, useState, startTransition } from 'react';
 import RSDWClient from 'react-server-dom-webpack/client';
 import { encodeInput } from './lib/renderers/utils.js';
 const { createFromFetch, encodeReply } = RSDWClient;
@@ -14,15 +14,27 @@ const checkStatus = async (responsePromise)=>{
     }
     return response;
 };
-const mergeElements = cache(async (a, b)=>{
-    const nextElements = {
-        ...await a,
-        ...await b
+const getCached = (c, m, k)=>(m.has(k) ? m : m.set(k, c())).get(k);
+const cache1 = new WeakMap();
+const mergeElements = (a, b)=>{
+    const getResult = async ()=>{
+        const nextElements = {
+            ...await a,
+            ...await b
+        };
+        delete nextElements._value;
+        return nextElements;
     };
-    delete nextElements._value;
-    return nextElements;
-});
-export const fetchRSC = cache((input, searchParamsString, rerender)=>{
+    const cache2 = getCached(()=>new WeakMap(), cache1, a);
+    return getCached(getResult, cache2, b);
+};
+const fetchCache = [];
+export const fetchRSC = (input, searchParamsString, setElements, cache = fetchCache)=>{
+    let entry = cache[0];
+    if (entry && entry[0] === input && entry[1] === searchParamsString) {
+        entry[2] = setElements;
+        return entry[3];
+    }
     const options = {
         async callServer (actionId, args) {
             const response = fetch(BASE_PATH + encodeInput(encodeURIComponent(actionId)), {
@@ -30,9 +42,10 @@ export const fetchRSC = cache((input, searchParamsString, rerender)=>{
                 body: await encodeReply(args)
             });
             const data = createFromFetch(checkStatus(response), options);
+            const setElements = entry[2];
             startTransition(()=>{
                 // FIXME this causes rerenders even if data is empty
-                rerender((prev)=>mergeElements(prev, data));
+                setElements((prev)=>mergeElements(prev, data));
             });
             return (await data)._value;
         }
@@ -42,43 +55,32 @@ export const fetchRSC = cache((input, searchParamsString, rerender)=>{
     const response = prefetched[url] || fetch(url);
     delete prefetched[url];
     const data = createFromFetch(checkStatus(response), options);
+    cache[0] = entry = [
+        input,
+        searchParamsString,
+        setElements,
+        data
+    ];
     return data;
-});
-export const prefetchRSC = cache((input, searchParamsString)=>{
+};
+export const prefetchRSC = (input, searchParamsString)=>{
     const prefetched = globalThis.__WAKU_PREFETCHED__ ||= {};
     const url = BASE_PATH + encodeInput(input) + (searchParamsString ? '?' + searchParamsString : '');
     if (!(url in prefetched)) {
         prefetched[url] = fetch(url);
     }
-});
+};
 const RefetchContext = createContext(()=>{
     throw new Error('Missing Root component');
 });
 const ElementsContext = createContext(null);
-// HACK there should be a better way...
-const createRerender = cache(()=>{
-    let rerender;
-    const stableRerender = (fn)=>{
-        rerender?.(fn);
-    };
-    const getRerender = ()=>stableRerender;
-    const setRerender = (newRerender)=>{
-        rerender = newRerender;
-    };
-    return [
-        getRerender,
-        setRerender
-    ];
-});
-export const Root = ({ initialInput, initialSearchParamsString, children })=>{
-    const [getRerender, setRerender] = createRerender();
-    const [elements, setElements] = useState(()=>fetchRSC(initialInput || '', initialSearchParamsString || '', getRerender()));
-    setRerender(setElements);
+export const Root = ({ initialInput, initialSearchParamsString, cache, children })=>{
+    const [elements, setElements] = useState(()=>fetchRSC(initialInput || '', initialSearchParamsString || '', (fn)=>setElements(fn), cache));
     const refetch = useCallback((input, searchParams)=>{
-        const data = fetchRSC(input, searchParams?.toString() || '', getRerender());
+        const data = fetchRSC(input, searchParams?.toString() || '', setElements, cache);
         setElements((prev)=>mergeElements(prev, data));
     }, [
-        getRerender
+        cache
     ]);
     return createElement(RefetchContext.Provider, {
         value: refetch

package/dist/config.d.ts

@@ -44,6 +44,12 @@ export interface Config {
      * Defaults to "entries.js".
      */
     entriesJs?: string;
+    /**
+     * The serve.js file relative distDir.
+     * This file is used for deployment.
+     * Defaults to "serve.js".
+     */
+    serveJs?: string;
     /**
      * Prefix for HTTP requests to indicate RSC requests.
      * Defaults to "RSC".

package/dist/dev.d.ts

@@ -1,4 +1,4 @@
-export { honoMiddleware } from './lib/middleware/hono-dev.js';
-export { connectMiddleware } from './lib/middleware/connect-dev.js';
+export { honoMiddleware as unstable_honoMiddleware } from './lib/middleware/hono-dev.js';
+export { connectMiddleware as unstable_connectMiddleware } from './lib/middleware/connect-dev.js';
 export { createHandler as unstable_createHandler } from './lib/handlers/handler-dev.js';
 export { build } from './lib/builder/build.js';

package/dist/dev.js

@@ -1,4 +1,4 @@
-export { honoMiddleware } from './lib/middleware/hono-dev.js';
-export { connectMiddleware } from './lib/middleware/connect-dev.js';
+export { honoMiddleware as unstable_honoMiddleware } from './lib/middleware/hono-dev.js';
+export { connectMiddleware as unstable_connectMiddleware } from './lib/middleware/connect-dev.js';
 export { createHandler as unstable_createHandler } from './lib/handlers/handler-dev.js';
 export { build } from './lib/builder/build.js';

package/dist/lib/builder/build.d.ts

@@ -3,9 +3,5 @@ export declare function build(options: {
     config?: Config;
     ssr?: boolean;
     env?: Record<string, string>;
-    vercel?: {
-        type: 'static' | 'serverless';
-    } | undefined;
-    cloudflare?: boolean;
-    deno?: boolean;
+    deploy?: 'vercel-static' | 'vercel-serverless' | 'cloudflare' | 'deno' | 'netlify-static' | 'netlify-functions' | 'aws-lambda' | undefined;
 }): Promise<void>;