{"_id":"@darkyzhou-powered/waku","name":"@darkyzhou-powered/waku","dist-tags":{"latest":"0.21.24"},"versions":{"0.21.24":{"name":"@darkyzhou-powered/waku","description":"⛩️ The minimal React framework","version":"0.21.24","type":"module","author":{"name":"Daishi Kato"},"homepage":"https://waku.gg","keywords":["react","minimal","framework"],"repository":{"type":"git","url":"git+https://github.com/wakujs/waku.git","directory":"packages/waku"},"exports":{"./package.json":"./package.json",".":{"types":"./dist/main.d.ts","react-server":"./dist/main.react-server.js","default":"./dist/main.js"},"./config":{"types":"./dist/config.d.ts","default":"./dist/config.js"},"./middleware/*":{"types":"./dist/middleware/*.d.ts","default":"./dist/middleware/*.js"},"./unstable_internals":{"types":"./dist/unstable_internals.d.ts","default":"./dist/unstable_internals.js"},"./unstable_hono":{"types":"./dist/unstable_hono.d.ts","default":"./dist/unstable_hono.js"},"./client":{"types":"./dist/client.d.ts","default":"./dist/client.js"},"./server":{"types":"./dist/server.d.ts","default":"./dist/server.js"},"./minimal/client":{"types":"./dist/minimal/client.d.ts","default":"./dist/minimal/client.js"},"./minimal/server":{"types":"./dist/minimal/server.d.ts","default":"./dist/minimal/server.js"},"./router":{"types":"./dist/router/base-types.d.ts","default":"./dist/router/base-types.js"},"./router/client":{"types":"./dist/router/client.d.ts","default":"./dist/router/client.js"},"./router/server":{"types":"./dist/router/server.d.ts","default":"./dist/router/server.js"}},"bin":{"waku":"cli.js"},"license":"MIT","engines":{"node":"^22.7.0 || ^20.8.0 || ^18.17.0"},"dependencies":{"@hono/node-server":"1.14.0","@swc/core":"1.11.13","@vitejs/plugin-react":"4.3.4","dotenv":"16.4.7","hono":"4.7.5","rsc-html-stream":"0.0.5","vite":"6.2.3"},"devDependencies":{"@netlify/functions":"^3.0.4","@swc/cli":"^0.6.0","react":"19.0.0","react-dom":"19.0.0","react-server-dom-webpack":"19.0.0","rollup":"^4.37.0","ts-expect":"^1.3.0","vitest":"3.0.9"},"peerDependencies":{"react":"~19.0.0","react-dom":"~19.0.0","react-server-dom-webpack":"~19.0.0"},"scripts":{"dev":"swc src -d dist -w --strip-leading-paths","test":"vitest run","test:watch":"vitest","compile":"rm -rf dist *.tsbuildinfo && pnpm run compile:code && pnpm run compile:types && cp ../../README.md .","compile:code":"swc src -d dist --strip-leading-paths","compile:types":"tsc --project tsconfig.json"},"_id":"@darkyzhou-powered/waku@0.21.24","bugs":{"url":"https://github.com/wakujs/waku/issues"},"_integrity":"sha512-TLN34YkdWLQis8rlEklexr7Mh1WS1FSWYcXZzKFyQQDBniXzP8e9g6KM6F+649gpX69z90Qtb+GbtMgGp22Y+w==","_resolved":"/private/var/folders/5s/6zykzt554351rw76ngvpnwlr0000gn/T/b34b9bddbcc576956dc26b8ca254aa98/darkyzhou-powered-waku-0.21.24.tgz","_from":"file:darkyzhou-powered-waku-0.21.24.tgz","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-TLN34YkdWLQis8rlEklexr7Mh1WS1FSWYcXZzKFyQQDBniXzP8e9g6KM6F+649gpX69z90Qtb+GbtMgGp22Y+w==","shasum":"5243d319677af5fdac7fd8ba4c878bd506e63b6c","tarball":"https://registry.npmjs.org/@darkyzhou-powered/waku/-/waku-0.21.24.tgz","fileCount":222,"unpackedSize":870579,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCCJRlAGpEhHAt8ONs5RG190uN00MnHC/AfZtAyMmUXQQIhAPcd6iWCeRYuZ1Gz+Vnu85zlgEMLJg6IiKYWRK8UXdM6"}]},"_npmUser":{"name":"darkyzhou","email":"darkyoooooo@gmail.com"},"directories":{},"maintainers":[{"name":"darkyzhou","email":"darkyoooooo@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/waku_0.21.24_1742997705971_0.7774182080433767"},"_hasShrinkwrap":false}},"time":{"created":"2025-03-26T14:01:45.904Z","0.21.24":"2025-03-26T14:01:46.274Z","modified":"2025-03-26T14:01:46.514Z"},"maintainers":[{"name":"darkyzhou","email":"darkyoooooo@gmail.com"}],"description":"⛩️ The minimal React framework","homepage":"https://waku.gg","keywords":["react","minimal","framework"],"repository":{"type":"git","url":"git+https://github.com/wakujs/waku.git","directory":"packages/waku"},"author":{"name":"Daishi Kato"},"bugs":{"url":"https://github.com/wakujs/waku/issues"},"license":"MIT","readme":"# Waku\n\n⛩️ The minimal React framework\n\nvisit [waku.gg](https://waku.gg) or `npm create waku@latest`\n\n[](https://github.com/wakujs/waku/actions?query=workflow%3ATest)\n[](https://www.npmjs.com/package/waku)\n[](https://www.npmjs.com/package/waku)\n[](https://discord.gg/MrQdmzd)\n\n \n\n## Introduction\n\n**Waku** _(wah-ku)_ or **わく** means “framework” in Japanese. As the minimal React framework, it’s designed 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.\n\nWe recommend other frameworks for heavy ecommerce or enterprise applications. Waku is a lightweight alternative bringing a fun developer experience to the server components era. Yes, let’s make React development fun again!\n\n> 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.\n\n## Getting started\n\nStart a new Waku project with the `create` command for your preferred package manager. It will scaffold a new project with our default [Waku starter](https://github.com/wakujs/waku/tree/main/examples/01_template).\n\n```sh\nnpm create waku@latest\n```\n\n**Node.js version requirement:** `^22.7.0` or `^20.8.0` or `^18.17.0`\n\n## Rendering\n\nWhile there’s a bit of a learning curve to modern React rendering, it introduces powerful new patterns of full-stack composability that are only possible with the advent of [server components](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md).\n\nSo 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. It’s way simpler than maintaining separate codebases for your backend and frontend.\n\nAnd 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 always 100% client components.\n\n> Future versions of Waku may provide additional opt-in APIs to abstract some of the complexity away for an improved developer experience.\n\n#### Server components\n\nServer 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.\n\n```tsx\n// server component\nimport db from 'some-db';\n\nimport { Gallery } from '../components/gallery';\n\nexport const Store = async () => {\n const products = await db.query('SELECT * FROM products');\n\n return ;\n};\n```\n\n#### Client components\n\nA `'use client'` directive placed at the top of a file will create a server-client boundary when 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.\n\n```tsx\n// client component\n'use client';\n\nimport { useState } from 'react';\n\nexport const Counter = () => {\n const [count, setCount] = useState(0);\n\n return (\n <>\n
Count: {count}
\n \n \n );\n};\n```\n\n#### Shared components\n\nSimple 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.\n\n```tsx\n// shared component\nexport const Headline = ({ children }) => {\n return
{children}
;\n};\n```\n\n#### Weaving patterns\n\nServer 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.\n\n```tsx\n// ./src/pages/_layout.tsx\nimport { Providers } from '../components/providers';\n\nexport default async function RootLayout({ children }) {\n return (\n \n {children}\n \n );\n}\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n } as const;\n};\n```\n\n```tsx\n// ./src/components/providers.tsx\n'use client';\n\nimport { Provider } from 'jotai';\n\nexport const Providers = ({ children }) => {\n return {children};\n};\n```\n\n#### Server-side rendering\n\nWaku provides static prerendering (SSG) and server-side rendering (SSR) options for both layouts and pages including all of their server _and_ client components. Note that SSR is a distinct concept from RSC.\n\n#### tl;dr:\n\nEach layout and page in Waku is composed of a React component hierarchy.\n\nIt begins with a server component at the top of the tree. Then at points down the hierarchy, 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.\n\nServer components can be rendered below this boundary, but only via composition (e.g., `children` props). Together they form [a new “React server” layer](https://github.com/reactwg/server-components/discussions/4) that runs _before_ the traditional “React client” layer with which you’re already familiar.\n\nClient components are still server-side rendered as SSR is separate from RSC. Please see the [linked diagrams](https://github.com/reactwg/server-components/discussions/4) for a helpful visual.\n\n#### Further reading\n\nTo learn more about the modern React architecture, we recommend [Making Sense of React Server Components](https://www.joshwcomeau.com/react/server-components/) and [The Two Reacts](https://overreacted.io/the-two-reacts/).\n\n## Routing\n\nWaku provides a minimal file-based “pages router” experience built for the server components era.\n\nIts underlying [low-level API](https://github.com/wakujs/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 like more!\n\n### Overview\n\nThe directory for file-based routing in Waku projects is `./src/pages`.\n\nLayouts 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 to specify the render method and other options.\n\nWaku currently supports two rendering options:\n\n- `'static'` for static prerendering (SSG)\n\n- `'dynamic'` for server-side rendering (SSR)\n\nLayouts are `static` by default while pages are `dynamic` by default.\n\nFor 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.\n\n```tsx\n// ./src/pages/_layout.tsx\nimport '../styles.css';\n\nimport { Providers } from '../components/providers';\nimport { Header } from '../components/header';\nimport { Footer } from '../components/footer';\n\n// Create root layout\nexport default async function RootLayout({ children }) {\n return (\n \n \n {children}\n \n \n );\n}\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n } as const;\n};\n```\n\n```tsx\n// ./src/pages/index.tsx\n\n// Create home page\nexport default async function HomePage() {\n const data = await getData();\n\n return (\n <>\n
{data.title}
\n
{data.content}
\n \n );\n}\n\nconst getData = async () => {\n /* ... */\n};\n\nexport const getConfig = async () => {\n return {\n render: 'dynamic',\n } as const;\n};\n```\n\n### Pages\n\nPages render a single route, segment route, or catch-all route based on the file system path (conventions below). All page components automatically receive two props related to the rendered route: `path` (string) and `query` (string).\n\n#### Single routes\n\nPages can be rendered as a single route (e.g., `about.tsx` or `blog/index.tsx`).\n\n```tsx\n// ./src/pages/about.tsx\n\n// Create about page\nexport default async function AboutPage() {\n return <>{/* ...*/};\n}\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n } as const;\n};\n```\n\n```tsx\n// ./src/pages/blog/index.tsx\n\n// Create blog index page\nexport default async function BlogIndexPage() {\n return <>{/* ...*/};\n}\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n } as const;\n};\n```\n\n#### Segment routes\n\nSegment routes (e.g., `[slug].tsx` or `[slug]/index.tsx`) are marked with brackets.\n\nThe 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'`).\n\nIf statically prerendering a segment route at build time, a `staticPaths` array must also be provided.\n\n```tsx\n// ./src/pages/blog/[slug].tsx\nimport type { PageProps } from 'waku/router';\n\n// Create blog article pages\nexport default async function BlogArticlePage({\n slug,\n}: PageProps<'/blog/[slug]'>) {\n const data = await getData(slug);\n\n return <>{/* ...*/};\n}\n\nconst getData = async (slug) => {\n /* ... */\n};\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n staticPaths: ['introducing-waku', 'introducing-pages-router'],\n } as const;\n};\n```\n\n```tsx\n// ./src/pages/shop/[category].tsx\nimport type { PageProps } from 'waku/router';\n\n// Create product category pages\nexport default async function ProductCategoryPage({\n category,\n}: PageProps<'/shop/[category]'>) {\n const data = await getData(category);\n\n return <>{/* ...*/};\n}\n\nconst getData = async (category) => {\n /* ... */\n};\n\nexport const getConfig = async () => {\n return {\n render: 'dynamic',\n } as const;\n};\n```\n\nStatic paths (or other config values) can also be generated programmatically.\n\n```tsx\n// ./src/pages/blog/[slug].tsx\nimport type { PageProps } from 'waku/router';\n\n// Create blog article pages\nexport default async function BlogArticlePage({\n slug,\n}: PageProps<'/blog/[slug]'>) {\n const data = await getData(slug);\n\n return <>{/* ...*/};\n}\n\nconst getData = async (slug) => {\n /* ... */\n};\n\nexport const getConfig = async () => {\n const staticPaths = await getStaticPaths();\n\n return {\n render: 'static',\n staticPaths,\n } as const;\n};\n\nconst getStaticPaths = async () => {\n /* ... */\n};\n```\n\n#### Nested segment routes\n\nRoutes can contain multiple segments (e.g., `/shop/[category]/[product]`) by creating folders with brackets as well.\n\n```tsx\n// ./src/pages/shop/[category]/[product].tsx\nimport type { PageProps } from 'waku/router';\n\n// Create product category pages\nexport default async function ProductDetailPage({\n category,\n product,\n}: PageProps<'/shop/[category]/[product]'>) {\n return <>{/* ...*/};\n}\n\nexport const getConfig = async () => {\n return {\n render: 'dynamic',\n } as const;\n};\n```\n\nFor static prerendering of nested segment routes, the `staticPaths` array is instead composed of ordered arrays.\n\n```tsx\n// ./src/pages/shop/[category]/[product].tsx\nimport type { PageProps } from 'waku/router';\n\n// Create product detail pages\nexport default async function ProductDetailPage({\n category,\n product,\n}: PageProps<'/shop/[category]/[product]'>) {\n return <>{/* ...*/};\n}\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n staticPaths: [\n ['same-category', 'some-product'],\n ['same-category', 'another-product'],\n ],\n } as const;\n};\n```\n\n#### Catch-all routes\n\nCatch-all or “wildcard” segment routes (e.g., `/app/[...catchAll]`) are marked with an ellipsis before the name and have indefinite segments.\n\nWildcard 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.\n\n```tsx\n// ./src/pages/app/[...catchAll].tsx\nimport type { PageProps } from 'waku/router';\n\n// Create dashboard page\nexport default async function DashboardPage({\n catchAll,\n}: PageProps<'/app/[...catchAll]'>) {\n return <>{/* ...*/};\n}\n\nexport const getConfig = async () => {\n return {\n render: 'dynamic',\n } as const;\n};\n```\n\n### Layouts\n\nLayouts are created with a special `_layout.tsx` file name and wrap the entire route and its descendents. They must accept a `children` prop of type `ReactNode`. While not required, you will typically want at least a root layout.\n\n#### Root layout\n\nThe 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.\n\n```tsx\n// ./src/pages/_layout.tsx\nimport '../styles.css';\n\nimport { Providers } from '../components/providers';\nimport { Header } from '../components/header';\nimport { Footer } from '../components/footer';\n\n// Create root layout\nexport default async function RootLayout({ children }) {\n return (\n \n \n \n \n {children}\n \n \n );\n}\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n } as const;\n};\n```\n\n```tsx\n// ./src/components/providers.tsx\n'use client';\n\nimport { createStore, Provider } from 'jotai';\n\nconst store = createStore();\n\nexport const Providers = ({ children }) => {\n return {children};\n};\n```\n\n#### Other layouts\n\nLayouts are also helpful in nested routes. For example, you can add a layout at `./pages/blog/_layout.tsx` to add a sidebar to both the blog index and all blog article pages.\n\n```tsx\n// ./src/pages/blog/_layout.tsx\nimport { Sidebar } from '../../components/sidebar';\n\n// Create blog layout\nexport default async function BlogLayout({ children }) {\n return (\n
\n
{children}
\n \n
\n );\n}\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n } as const;\n};\n```\n\n### Root element\n\nThe attributes of ``, ``, or `` elements can be customized with the root element API. Create a special `_root.tsx` file in the `./src/pages` directory that accepts a `children` prop of type `ReactNode`.\n\n```tsx\n// ./src/pages/_root.tsx\n\n// Create root element\nexport default async function RootElement({ children }) {\n return (\n \n \n {children}\n \n );\n}\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n } as const;\n};\n```\n\n## Navigation\n\n### Link\n\nThe`` component should be used for internal links. It accepts a `to` prop for the destination, which is automatically prefetched ahead of the navigation.\n\n```tsx\n// ./src/pages/index.tsx\nimport { Link } from 'waku';\n\nexport default async function HomePage() {\n return (\n <>\n
Home
\n About\n \n );\n}\n```\n\n### useRouter\n\nThe `useRouter` hook can be used to inspect the current route or perform programmatic navigation.\n\n#### router properties\n\nThe `router` object has two properties related to the current route: `path` (string) and `query` (string).\n\n```tsx\n'use client';\n\nimport { useRouter_UNSTABLE as useRouter } from 'waku';\n\nexport const Component = () => {\n const { path, query } = useRouter();\n\n return (\n <>\n
current path: {path}
\n
current query: {query}
\n \n );\n};\n```\n\n#### router methods\n\nThe `router` object also contains several methods for programmatic navigation:\n\n- `router.push(to: string)` - navigate to the provided route\n\n- `router.prefetch(to: string)` - prefetch the provided route\n\n- `router.replace(to: string)` - replace the current history entry\n\n- `router.reload()` - reload the current route\n\n- `router.back()` - navigate to the previous entry in the session history\n\n- `router.forward()` - navigate to the next entry in the session history\n\n```tsx\n'use client';\n\nimport { useRouter_UNSTABLE as useRouter } from 'waku';\n\nexport const Component = () => {\n const router = useRouter();\n\n return (\n <>\n \n \n \n );\n};\n```\n\n## Metadata\n\nWaku automatically hoists any title, meta, and link tags to the document head. That means adding meta tags is as simple as adding them to any of your layout or page components.\n\n```tsx\n// ./src/pages/_layout.tsx\nexport default async function RootLayout({ children }) {\n return (\n <>\n \n \n {children}\n \n );\n}\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n } as const;\n};\n```\n\n```tsx\n// ./src/pages/index.tsx\nexport default async function HomePage() {\n return (\n <>\n Waku\n \n
Waku
\n
Hello world!
\n \n );\n}\n\nexport const getConfig = async () => {\n return {\n render: 'static',\n } as const;\n};\n```\n\nMetadata can also be generated programmatically.\n\n```tsx\n// ./src/pages/index.tsx\nexport default async function HomePage() {\n return (\n <>\n