How wakujs/waku works
Based on our deep dive into the file tree and the comprehensive README, this project is a monorepo for Waku—a minimal React framework. Its purpose is to provide a lightweight, full-stack React framework that leverages server components to give developers a “fun” and efficient way to build websites and web applications. In short, it focuses on a modern approach to rendering, routing, and data fetching by enabling smooth transitions between server and client components.
Main High-Level Components
• Core Framework (packages/waku): This contains the engine for handling the rendering, routing, and build-time optimizations. It includes modules such as the router (file-based routing and create-pages utilities), middleware (for handling context, fallback, and dev-server logic), plugins (for integrations with Vite, AWS Lambda, Cloudflare, etc.), and renderers that manage both traditional SSR and newer server component flows.
• CLI & Scaffolding (packages/create-waku): Provides command-line interface utilities to scaffold new Waku projects.
• Website & Documentation (packages/website and docs folder): These support community content, developer documentation, examples, and demos.
• Examples & Tests (examples directory & e2e folder): A wide array of example projects (both TypeScript and JavaScript templates) and end-to-end tests that show how to use various aspects of the framework (routing, full SSR or SSG rendering, RSC, server actions, etc.).
• Configuration, Build, and Utility Files: Including tsconfig, PostCSS config, ESLint config, and many CI/CD workflow files (in .github and .codesandbox folders) that ensure integration with deployment and testing environments.
Out the Relationships and Interactions
• How the Core Framework interacts with its various submodules:
• The Routing Engine relies upon the file-based “pages router” (with conventions for single routes, segment, nested, and catch-all routes) and supports dynamic and static rendering through configuration functions (getConfig).
• The Rendering Engine differentiates between server components (that can be asynchronous and handle server-only logic) and client components (marked with ‘use client’) – clearly highlighting the server-client boundary.
• Server Actions: Demonstrate how inline and separate server action functions (with the “use server” directive) are integrated into the overall rendering flow and can be passed down as props to client components.
• Role of Plugins and Builders: These modules modify and extend the Vite configuration, enable deployments to various platforms (AWS Lambda, Cloudflare, Netlify, etc.), and help in code transformation and optimization.
• Integrations with external libraries: Such as Jotai for state management and any other supporting libraries mentioned in the README.
Architectural Patterns and Principles
• Separation of Concerns: The architecture splits responsibilities between routing, rendering, and build/deployment aspects.
• Server-Client Boundary: Clearly illustrate how the ‘use client’ directive marks a boundary within the component tree, causing a shift from server to client rendered components.
• Modular & Pluggable Design: Break down the system into reusable modules (plugins, middleware, renderers) that the framework leverages to support various deployment targets.
• File-Based Routing Convention: Emphasize the convention over configuration aspect where directory structure (e.g., src/pages with special files like _layout.tsx, _root.tsx) drives the routing behavior.
Essential Elements
• “Core Framework (waku)” – with internal submodules: Router, Middleware, Plugins, Renderers, Server utilities.
• “CLI/Scaffolding (create-waku)” – for project generation.
• “Examples & Tests” – showcasing usage examples and integration tests.
• “Website & Docs” – supporting developer resources.
• Flow paths from server actions, data fetching modules, and build scripts to the final output deployments.