waku 0.20.0-beta.2 → 0.20.0

package/README.md

@@ -49,11 +49,11 @@ import db from 'some-db';
 
 import { Gallery } from '../components/gallery.js';
 
-export default async function StorePage() {
+export const Store = async () => {
   const products = await db.query('SELECT * FROM products');
 
   return <Gallery products={products} />;
-}
+};
 ```
 
 #### Client components
@@ -145,11 +145,11 @@ To learn more about the modern React architecture, we recommend [Making Sense of
 
 Waku provides a familiar file-based “pages router” experience built for the modern React server components era.
 
-Its underlying [low-level API](https://github.com/dai-shi/waku/blob/main/docs/minimal-api.mdx) is also available for those that prefer programmatic routing. This documentation covers file-baesed routing since many React developers prefer it, but please feel free to try both and see which you like more.
+Its underlying [low-level API](https://github.com/dai-shi/waku/blob/main/docs/create-pages.mdx) is also available for those that prefer programmatic routing. This documentation covers file-based routing since many React developers prefer it, but please feel free to try both and see which you prefer.
 
 ### Overview
 
-The directory for file-based routing in Waku projects is `./src/pages`. Layouts and pages can be created as easily as making a new file with two exports: a default function for the React component and a named `getConfig` function to specify the render method and other configuration details.
+The directory for file-based routing in Waku projects is `./src/pages`. Layouts and pages can be created by making a new file with two exports: a default function for the React component and a named `getConfig` function that returns a configuration object including the render method and other options.
 
 Waku currently supports two rendering options: `'static'` for static prerendering (SSG) or `'dynamic'` for server-side rendering (SSR).
 
@@ -158,6 +158,9 @@ For example, you can statically prerender a global header and footer in the root
 ```tsx
 // ./src/pages/_layout.tsx
 
+import { Header } from '../components/header.js';
+import { Footer } from '../components/footer.js';
+
 // Create root layout
 export default async function RootLayout({ children }) {
   return (
@@ -186,6 +189,7 @@ export default async function HomePage() {
   return (
     <div>
       <h1>{data.someDynamicTitle}</h1>
+      <div>{data.someDynamicContent}</div>
     </div>
   );
 }
@@ -205,7 +209,7 @@ export const getConfig = async () => {
 
 #### Single routes
 
-Pages can be rendered as a single route (e.g., `/about.tsx` or `/blog.tsx`).
+Pages can be rendered as a single route (e.g., `/about` or `/blog`).
 
 ```tsx
 // ./src/pages/about.tsx
@@ -223,7 +227,7 @@ export const getConfig = async () => {
 ```
 
 ```tsx
-// ./src/pages/blog.tsx
+// ./src/pages/blog/index.tsx
 
 // Create blog index page
 export default async function BlogIndexPage() {
@@ -239,7 +243,7 @@ export const getConfig = async () => {
 
 #### Segment routes
 
-Pages can also render a segment route (e.g., `/blog/[slug].tsx`). The rendered React component automatically receives a prop named by the segment (e.g, `slug`) with the value of the rendered route (e.g., `'introducing-waku'`). If statically prerendering a segment route at build time, a `staticPaths` array must also be provided.
+Pages can also render a segment route (e.g., `/blog/[slug]`). The rendered React component automatically receives a prop named by the segment (e.g, `slug`) with the value of the rendered segment (e.g., `'introducing-waku'`). If statically prerendering a segment route at build time, a `staticPaths` array must also be provided.
 
 ```tsx
 // ./src/pages/blog/[slug].tsx
@@ -264,7 +268,7 @@ export const getConfig = async () => {
 ```
 
 ```tsx
-// ./src/pages/shop/[category].tsx
+// ./src/pages/shop/[category]/index.tsx
 
 // Create product category pages
 export default async function ProductCategoryPage({ category }) {
@@ -316,7 +320,7 @@ const getStaticPaths = async () => {
 
 #### Nested segment routes
 
-Routes can contain multiple segments (e.g., `/shop/[category]/[product].tsx`).
+Routes can contain multiple segments (e.g., `/shop/[category]/[product]`).
 
 ```tsx
 // ./src/pages/shop/[category]/[product].tsx
@@ -347,8 +351,8 @@ export const getConfig = async () => {
   return {
     render: 'static',
     staticPaths: [
-      ['someCategory', 'someProduct'],
-      ['someCategory', 'anotherProduct'],
+      ['some-category', 'some-product'],
+      ['some-category', 'another-product'],
     ],
   };
 };
@@ -356,7 +360,7 @@ export const getConfig = async () => {
 
 #### Catch-all routes
 
-Catch-all or "wildcard" routes (e.g., `/app/[...catchAll].tsx`) have indefinite segments. Wildcard routes receive a prop with segment values as an ordered array.
+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.
 
@@ -381,7 +385,7 @@ Layouts are created with a special `_layout.tsx` file name and wrap the entire r
 
 #### Root layout
 
-The root layout placed at `./src/pages/_layout.tsx` is especially useful. It can be used for setting global styles, global metadata, global providers, global data, and global components, such as a header and footer.
+The root layout placed at `./pages/_layout.tsx` is especially useful. It can be used for setting global styles, global metadata, global providers, global data, and global components, such as a header and footer.
 
 ```tsx
 // ./src/pages/_layout.tsx
@@ -395,14 +399,20 @@ import { Footer } from '../components/footer.js';
 export default async function RootLayout({ children }) {
   return (
     <Providers>
-      <meta property="og:image" content="/images/preview.png" />
       <link rel="icon" type="image/png" href="/images/favicon.png" />
+      <meta property="og:image" content="/images/opengraph.png" />
       <Header />
       <main>{children}</main>
       <Footer />
     </Providers>
   );
 }
+
+export const getConfig = async () => {
+  return {
+    render: 'static',
+  };
+};
 ```
 
 ```tsx
@@ -420,7 +430,7 @@ export const Providers = ({ children }) => {
 
 #### Other layouts
 
-Layouts are also helpful further down the tree. For example, you could add a layout at `./src/pages/blog/_layout.tsx` 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 `./pages/blog/_layout.tsx` to add a sidebar to both the blog index and all blog article pages.
 
 ```tsx
 // ./src/pages/blog/_layout.tsx
@@ -435,10 +445,18 @@ export default async function BlogLayout({ children }) {
     </div>
   );
 }
+
+export const getConfig = async () => {
+  return {
+    render: 'static',
+  };
+};
 ```
 
 ## Navigation
 
+### Link
+
 Internal links should be made with the Waku `<Link />` component. It accepts a `to` prop for the destination, which is automatically prefetched ahead of the navigation.
 
 ```tsx
@@ -455,56 +473,64 @@ export default async function HomePage() {
 }
 ```
 
-## Static assets
+### useRouter
 
-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.
+The `useRouter` hook can be used to inspect the current route or perform programmatic navigation.
 
-For example, an image added to `./public/images/logo.svg` can be rendered via `<img src="/images/logo.svg" />`.
+#### router properties
 
-## File system
-
-Files placed in a special `./private` folder of the Waku project root directory can be securely accessed in React server components.
+The `router` object has a `value` property with two additional properties related to the current route: `path` (string) and `searchParams` ([URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)).
 
 ```tsx
-export default async function HomePage() {
-  const file = readFileSync('./private/README.md', 'utf8');
-  /* ... */
-}
-```
-
-## 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.
+'use client';
 
-```tsx
-// ./src/pages/blog/[slug].tsx
-import { MDX } from '../../components/mdx.js';
-import { getArticle } from '../../lib/get-article.js';
+import { useRouter_UNSTABLE as useRouter } from 'waku';
 
-export default async function BlogArticlePage({ slug }) {
-  const article = await getArticle(slug);
+export const Component = () => {
+  const router = useRouter();
+  const { path, searchParams } = router.value;
 
   return (
     <>
-      <title>{article.frontmatter.title}</title>
-      <h1>{article.frontmatter.title}</h1>
-      <MDX>{article.content}</MDX>
+      <div>current path: {path}</div>
+      <div>current searchParams: {searchParams.toString()}</div>
     </>
   );
-}
+};
 ```
 
-### Client
+#### router methods
 
-Data should be fetched on the server when possible for the best user experience, but all data fetching libraries such as React Query should be compatible with Waku.
+The `router` object also contains several methods for programmatic navigation:
 
-## State management
+- `router.push(to: string)` - navigate to the provided route
 
-We recommend [Jotai](https://jotai.org) for global React state management based on the atomic model's performance and scalability, but Waku should be compatible with all React state management libraries such as Zustand and Valtio.
+- `router.prefetch(to: string)` - prefetch the provided route
 
-We're exploring a deeper integration of atomic state management into Waku to achieve the performance and developer experience of signals while preserving React's declarative programming model.
+- `router.replace(to: string)` - replace the current history entry
+
+- `router.reload()` - reload the current route
+
+- `router.back()` - navigate to the previous entry in the session history
+
+- `router.forward()` - navigate to the next entry in the session history
+
+```tsx
+'use client';
+
+import { useRouter_UNSTABLE as useRouter } from 'waku';
+
+export const Component = () => {
+  const router = useRouter();
+
+  return (
+    <>
+      <button onClick={() => router.push('/')}>Home</button>
+      <button onClick={() => router.back()}>Back</button>
+    </>
+  );
+};
+```
 
 ## Metadata
 
@@ -515,12 +541,18 @@ Waku automatically hoists any title, meta, and link tags to the document head. S
 export default async function RootLayout({ children }) {
   return (
     <>
-      <meta property="og:image" content="/images/preview.png" />
       <link rel="icon" type="image/png" href="/images/favicon.png" />
+      <meta property="og:image" content="/images/opengraph.png" />
       {children}
     </>
   );
 }
+
+export const getConfig = async () => {
+  return {
+    render: 'static',
+  };
+};
 ```
 
 ```tsx
@@ -535,6 +567,12 @@ export default async function HomePage() {
     </>
   );
 }
+
+export const getConfig = async () => {
+  return {
+    render: 'static',
+  };
+};
 ```
 
 Metadata could also be generated programmatically.
@@ -564,6 +602,12 @@ const Head = async () => {
 const getMetadata = async () => {
   /* ... */
 };
+
+export const getConfig = async () => {
+  return {
+    render: 'static',
+  };
+};
 ```
 
 ## Styling
@@ -579,6 +623,12 @@ import '../styles.css';
 export default async function RootLayout({ children }) {
   return <main>{children}</main>;
 }
+
+export const getConfig = async () => {
+  return {
+    render: 'static',
+  };
+};
 ```
 
 ```css
@@ -605,6 +655,72 @@ export default {
 };
 ```
 
+## Static assets
+
+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" />`.
+
+## File system
+
+Files placed in a special `./private` folder of the Waku project root directory can be securely accessed in React server components.
+
+```tsx
+export default async function HomePage() {
+  const file = readFileSync('./private/README.md', 'utf8');
+  /* ... */
+}
+
+export const getConfig = async () => {
+  return {
+    render: 'static',
+  };
+};
+```
+
+## 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.
+
+```tsx
+// ./src/pages/blog/[slug].tsx
+import { MDX } from '../../components/mdx.js';
+import { getArticle, getStaticPaths } from '../../lib/blog.js';
+
+export default async function BlogArticlePage({ slug }) {
+  const article = await getArticle(slug);
+
+  return (
+    <>
+      <title>{article.frontmatter.title}</title>
+      <h1>{article.frontmatter.title}</h1>
+      <MDX>{article.content}</MDX>
+    </>
+  );
+}
+
+export const getConfig = async () => {
+  const staticPaths = await getStaticPaths();
+
+  return {
+    render: 'static',
+    staticPaths,
+  };
+};
+```
+
+### Client
+
+Data should be fetched on the server when possible for the best user experience, but all data fetching libraries such as React Query should be compatible with Waku.
+
+## State management
+
+We recommend [Jotai](https://jotai.org) for global React state management based on the atomic model's performance and scalability, but Waku should be compatible with all React state management libraries such as Zustand and Valtio.
+
+We're exploring a deeper integration of atomic state management into Waku to achieve the performance and developer experience of signals while preserving React's declarative programming model.
+
 ## Environment variables
 
 It's important to distinguish environment variables that must be kept secret from those that can be made public.

package/dist/lib/plugins/vite-plugin-rsc-delegate.js

@@ -27,6 +27,34 @@ export function rscDelegatePlugin(callback) {
     let mode = 'development';
     let base = '/';
     let server;
+    const updateStyle = async (id, importer)=>{
+        const resolvedSource = await server.pluginContainer.resolveId(id, importer, {
+            ssr: true
+        });
+        if (resolvedSource?.id) {
+            const { default: source } = await server.ssrLoadModule(resolvedSource.id);
+            const transformedResult = await server.transformRequest(resolvedSource.id);
+            if (transformedResult) {
+                moduleImports.add(resolvedSource.id);
+                callback({
+                    type: 'custom',
+                    event: 'module-import',
+                    data: {
+                        ...transformedResult,
+                        source,
+                        id: resolvedSource.id,
+                        css: true
+                    }
+                });
+            }
+        }
+    };
+    const styleFiles = new Map(); // id -> importer
+    const updateAllStyles = async ()=>{
+        for (const [id, importer] of styleFiles){
+            await updateStyle(id, importer);
+        }
+    };
     return {
         name: 'rsc-delegate-plugin',
         configResolved (config) {
@@ -38,6 +66,7 @@ export function rscDelegatePlugin(callback) {
         },
         async handleHotUpdate (ctx) {
             if (mode === 'development') {
+                await updateAllStyles(); // FIXME is this too aggressive?
                 if (moduleImports.has(ctx.file)) {
                     // re-inject
                     const transformedResult = await server.transformRequest(ctx.file);
@@ -84,26 +113,8 @@ export function rscDelegatePlugin(callback) {
                                 data: source
                             });
                         } else if (CSS_LANGS_RE.test(item.source.value)) {
-                            const resolvedSource = await server.pluginContainer.resolveId(item.source.value, id, {
-                                ssr: true
-                            });
-                            if (resolvedSource?.id) {
-                                const { default: source } = await server.ssrLoadModule(resolvedSource.id);
-                                const transformedResult = await server.transformRequest(resolvedSource.id);
-                                if (transformedResult) {
-                                    moduleImports.add(resolvedSource.id);
-                                    callback({
-                                        type: 'custom',
-                                        event: 'module-import',
-                                        data: {
-                                            ...transformedResult,
-                                            source,
-                                            id: resolvedSource.id,
-                                            css: true
-                                        }
-                                    });
-                                }
-                            }
+                            styleFiles.set(item.source.value, id);
+                            await updateStyle(item.source.value, id);
                         }
                     }
                 }

package/dist/lib/plugins/vite-plugin-rsc-hmr.js

@@ -1,4 +1,4 @@
-import { joinPath, fileURLToFilePath, decodeFilePathFromAbsolute } from '../utils/path.js';
+import { joinPath, fileURLToFilePath, decodeFilePathFromAbsolute, filePathToFileURL } from '../utils/path.js';
 const injectingHmrCode = `
 import { createHotContext as __vite__createHotContext } from "/@vite/client";
 import.meta.hot = __vite__createHotContext(import.meta.url);
@@ -22,7 +22,7 @@ if (import.meta.hot && !globalThis.__WAKU_HMR_CONFIGURED__) {
     document.head.appendChild(script);
     // avoid HMR flash by first applying the new and removing the old styles 
     if (style) {
-      queueMicrotask(style.remove);
+      queueMicrotask(() => style.parentElement?.removeChild(style));
     }
   });
 }
@@ -91,6 +91,18 @@ export function rscHmrPlugin() {
 }
 `);
             }
+        },
+        handleHotUpdate ({ file }) {
+            const moduleLoading = globalThis.__webpack_module_loading__;
+            const moduleCache = globalThis.__webpack_module_cache__;
+            const id = filePathToFileURL(file);
+            if (moduleLoading.has(id) && moduleCache.has(id)) {
+                moduleLoading.delete(id);
+                moduleCache.delete(id);
+                moduleLoading.set(id, viteServer.ssrLoadModule(file).then((m)=>{
+                    moduleCache.set(id, m);
+                }));
+            }
         }
     };
 }
@@ -124,12 +136,12 @@ function hotImport(viteServer, source) {
 const modulePendingMap = new WeakMap();
 function moduleImport(viteServer, result) {
     const hot = viteHot(viteServer);
-    let sourceSet = modulePendingMap.get(hot);
-    if (!sourceSet) {
-        sourceSet = new Set();
-        modulePendingMap.set(hot, sourceSet);
+    let sources = modulePendingMap.get(hot);
+    if (!sources) {
+        sources = new Map();
+        modulePendingMap.set(hot, sources);
     }
-    sourceSet.add(result);
+    sources.set(result.id, result);
     hot.send({
         type: 'custom',
         event: 'module-import',
@@ -138,13 +150,13 @@ function moduleImport(viteServer, result) {
 }
 async function generateInitialScripts(viteServer) {
     const hot = viteHot(viteServer);
-    const sourceSet = modulePendingMap.get(hot);
-    if (!sourceSet) {
+    const sources = modulePendingMap.get(hot);
+    if (!sources) {
         return [];
     }
     const scripts = [];
     let injectedBlockingViteClient = false;
-    for (const result of sourceSet){
+    for (const result of sources.values()){
         // CSS modules do not support result.source (empty) since ssr-transforming them gives the css keys
         // and client-transforming them gives the script tag for injecting them.
         if (result.id.endsWith('.module.css')) {

package/dist/lib/renderers/html-renderer.js

@@ -148,13 +148,14 @@ export const renderHtml = async (opts)=>{
         get (_target, filePath) {
             return new Proxy({}, {
                 get (_target, name) {
-                    const file = filePath.slice(config.basePath.length);
-                    // TODO too long, we need to refactor this logic
                     if (isDev) {
-                        const filePath = file.startsWith('@fs/') ? file.slice('@fs'.length) : encodeFilePathToAbsolute(joinPath(opts.rootDir, file.split('?')[0]));
+                        // TODO too long, we need to refactor this logic
+                        let file = filePath.slice(config.basePath.length);
+                        file = file.split('?')[0];
+                        file = file.startsWith('@fs/') ? file.slice('@fs'.length) : encodeFilePathToAbsolute(joinPath(opts.rootDir, file));
                         const wakuDist = joinPath(fileURLToFilePath(import.meta.url), '../../..');
-                        if (filePath.startsWith(wakuDist)) {
-                            const id = 'waku' + filePath.slice(wakuDist.length).replace(/\.\w+$/, '');
+                        if (file.startsWith(wakuDist)) {
+                            const id = 'waku' + file.slice(wakuDist.length).replace(/\.\w+$/, '');
                             if (!moduleLoading.has(id)) {
                                 moduleLoading.set(id, import(/* @vite-ignore */ id).then((m)=>{
                                     moduleCache.set(id, m);
@@ -168,7 +169,7 @@ export const renderHtml = async (opts)=>{
                                 name
                             };
                         }
-                        const id = filePathToFileURL(filePath);
+                        const id = filePathToFileURL(file);
                         if (!moduleLoading.has(id)) {
                             moduleLoading.set(id, opts.loadServerFile(id).then((m)=>{
                                 moduleCache.set(id, m);
@@ -183,7 +184,7 @@ export const renderHtml = async (opts)=>{
                         };
                     }
                     // !isDev
-                    const id = file;
+                    const id = filePath.slice(config.basePath.length);
                     if (!moduleLoading.has(id)) {
                         moduleLoading.set(id, opts.loadModule(joinPath(config.ssrDir, id)).then((m)=>{
                             moduleCache.set(id, m);

package/dist/main.d.ts

@@ -1,3 +1,3 @@
-export { Link } from 'waku/router/client';
+export { Link, useRouter_UNSTABLE } from 'waku/router/client';
 export { createPages } from 'waku/router/server';
 export { getEnv } from 'waku/server';

package/dist/main.js

@@ -1,3 +1,3 @@
-export { Link } from 'waku/router/client';
+export { Link, useRouter_UNSTABLE } from 'waku/router/client';
 export { createPages } from 'waku/router/server';
 export { getEnv } from 'waku/server';

package/dist/router/client.d.ts

@@ -5,15 +5,15 @@ declare global {
         readonly env: Record<string, string>;
     }
 }
-declare const parseLocation: () => RouteProps;
-type ChangeLocation = (path?: string, searchParams?: URLSearchParams, options?: {
-    hash?: string;
-    method?: 'pushState' | 'replaceState' | false;
-    scrollTo?: ScrollToOptions | false;
-    unstable_skipRefetch?: boolean;
-}) => void;
-export declare function useChangeLocation(): ChangeLocation;
-export declare function useLocation(): RouteProps;
+export declare function useRouter_UNSTABLE(): {
+    value: RouteProps;
+    push: (to: string) => void;
+    replace: (to: string) => void;
+    reload: () => void;
+    back: () => void;
+    forward: () => void;
+    prefetch: (to: string) => void;
+};
 export type LinkProps = {
     to: string;
     pending?: ReactNode;
@@ -24,7 +24,7 @@ export type LinkProps = {
 export declare function Link({ to, children, pending, notPending, unstable_prefetchOnEnter, ...props }: LinkProps): ReactElement;
 type RouterData = [
     shouldSkip?: ShouldSkip,
-    locationListners?: Set<(pathname: string, searchParams: URLSearchParams) => void>
+    locationListners?: Set<(pathname: string, searchParamsString: string) => void>
 ];
 export declare function Router({ routerData }: {
     routerData?: RouterData | undefined;
@@ -39,9 +39,9 @@ export declare function Router({ routerData }: {
  * ServerRouter for SSR
  * This is not a public API.
  */
-export declare function ServerRouter({ children, loc, }: {
+export declare function ServerRouter({ children, route, }: {
     children: ReactNode;
-    loc: ReturnType<typeof parseLocation>;
+    route: RouteProps;
 }): import("react").FunctionComponentElement<{
     children?: ReactNode;
 }>;