npm - @funstack/static - Versions diffs - 0.0.3 → 0.0.4 - Mend

@funstack/static 0.0.3 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +9 -12
package/dist/docs/MigratingFromViteSPA.md +321 -0
package/dist/docs/index.md +2 -0
package/dist/docs/learn/LazyServerComponents.md +120 -0
package/dist/docs/learn/OptimizingPayloads.md +2 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -2,9 +2,6 @@
 A maximally minimal React framework. Vite plugin for static sites with RSC support.
-> [!WARNING]
-> This is work in progress.
 ## Features
 - :x: **No server runs** - perfect for CSR (Client Side Rendering) app and static deployment.
@@ -38,22 +35,22 @@ export default defineConfig({
 });
 ```
-## CLI Commands
+## Documentation
-### `funstack-static-skill-installer`
+For detailed API documentation and guides, visit the **[Documentation](https://uhyo.github.io/funstack-static/)**.
-Installs the `funstack-static-knowledge` skill for AI coding assistants (like [Claude Code](https://docs.anthropic.com/en/docs/claude-code)).
+### :robot: FUNSTACK Static Skill
+FUNSTACK Static provides an Agent Skill to feed your AI agents with knowledge about this framework. After installing `@funstack/static`, run the following command to add the skill to the project:
 ```sh
 npx funstack-static-skill-installer
+# or
+yarn funstack-static-skill-installer
+# or
+pnpm funstack-static-skill-installer
 ```
-This command registers the skill that provides AI assistants with knowledge about the FUNSTACK Static framework, including API references, best practices, and architectural guidance. After installation, your AI assistant will be able to better understand and work with your FUNSTACK Static project.
-## Documentation
-For detailed API documentation and guides, visit the **[Documentation](https://uhyo.github.io/funstack-static/)**.
 ## License
 MIT

package/dist/docs/MigratingFromViteSPA.md ADDED Viewed

@@ -0,0 +1,321 @@
+# Migrating from Vite SPA
+Already have a Vite-powered React SPA? This guide walks you through migrating to FUNSTACK Static to unlock React Server Components and improved performance.
+## Overview
+Migrating from a standard Vite React SPA to FUNSTACK Static involves:
+1. Installing FUNSTACK Static
+2. Adding the Vite plugin
+3. Restructuring your entry point into Root and App components
+4. Converting appropriate components to Server Components
+The good news: your existing client components work as-is. You can migrate incrementally.
+## Step 1: Install Dependencies
+Add FUNSTACK Static to your existing project:
+```bash
+npm install @funstack/static
+```
+Or with pnpm:
+```bash
+pnpm add @funstack/static
+```
+**Hint:** at this point, a skill installer command is available to add FUNSTACK Static knowledge to your AI agents. Run `npx funstack-static-skill-installer` or similar to add the skill. Then you can ask your AI assistant for help with the migration!
+## Step 2: Update Vite Config
+Modify your `vite.config.ts` to add the FUNSTACK Static plugin:
+```typescript
+import { funstackStatic } from "@funstack/static";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+export default defineConfig({
+  plugins: [
+    funstackStatic({
+      root: "./src/Root.tsx",
+      app: "./src/App.tsx",
+    }),
+    react(),
+  ],
+});
+```
+Note that the existing React plugin remains; FUNSTACK Static works alongside it.
+## Step 3: Create the Root Component
+The Root component replaces your `index.html` file. Create `src/Root.tsx`:
+```tsx
+// src/Root.tsx
+import type React from "react";
+export default function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>My App</title>
+        {/* Add your existing <head> content here */}
+      </head>
+      <body>
+        <div id="root">{children}</div>
+      </body>
+    </html>
+  );
+}
+```
+Move any content from your `index.html` `<head>` section into this component.
+## Step 4: Update Your App Entry Point
+Your existing `main.tsx` or `index.tsx` likely looks like this:
+```tsx
+// Before: src/main.tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import "./index.css";
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
+```
+With FUNSTACK Static, you no longer need this file. Instead, your `App.tsx` becomes the entry point and is automatically rendered as a Server Component:
+```tsx
+// After: src/App.tsx
+import "./index.css";
+import { HomePage } from "./pages/HomePage";
+export default function App() {
+  return <HomePage />;
+}
+```
+You can delete `main.tsx` - FUNSTACK Static handles the rendering.
+## Step 5: Mark Client Component Boundaries
+In a standard Vite SPA, all components are client components. With FUNSTACK Static, components are Server Components by default.
+As a starting point, it is possible to mark the App component as a client component by adding `"use client"` at the top:
+```tsx
+// src/App.tsx
+"use client";
+// ...rest of the code
+```
+This makes the entire app a client component, similar to your previous SPA.
+However, to take advantage of Server Components, you should incrementally convert components to Server Components. This can be done by removing `"use client"` from components that don't need it and instead adding it only to components that require client-side interactivity.
+**Note:** you only need to add `"use client"` to components that are **directly imported by Server Components**. This marks the boundary between server and client code. Components imported by other client components don't need the directive.
+```tsx
+// src/components/Counter.tsx
+"use client";
+import { useState } from "react";
+import { Button } from "./Button"; // No "use client" needed in Button.tsx
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <Button onClick={() => setCount(count + 1)}>Count: {count}</Button>;
+}
+```
+In this example, `Counter.tsx` needs `"use client"` because it's imported by a Server Component. But `Button.tsx` doesn't need it since it's only imported by `Counter`, which is already a client component.
+A component is a client component if it:
+- Use client-only hooks (`useState`, `useEffect`, `useContext`, etc.)
+- Attach event handlers (`onClick`, `onChange`, etc.)
+- Use browser-only APIs (`window`, `document`, `localStorage`, etc.)
+## Step 6: Update Your Router (If Applicable)
+If you're using React Router or another client-side router, you have two options:
+### Option A: Keep Your Existing Router
+You can continue using your existing router as a client component:
+```tsx
+// src/App.tsx
+import { ClientRouter } from "./ClientRouter";
+export default function App() {
+  return <ClientRouter />;
+}
+```
+```tsx
+// src/ClientRouter.tsx
+"use client";
+import { BrowserRouter, Routes, Route } from "react-router-dom";
+import { Home } from "./pages/Home";
+import { About } from "./pages/About";
+export function ClientRouter() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<Home />} />
+        <Route path="/about" element={<About />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+### Option B: Use a Server-Compatible Router
+For better performance, consider migrating to [FUNSTACK Router](https://github.com/uhyo/funstack-router) which is a standalone router for SPAs but still integrates well with Server Components.
+```bash
+npm install @funstack/router
+```
+```tsx
+// src/App.tsx
+import { Router } from "@funstack/router";
+import { route } from "@funstack/router/server";
+import { Home } from "./pages/Home";
+import { About } from "./pages/About";
+const routes = [
+  route({ path: "/", component: <Home /> }),
+  route({ path: "/about", component: <About /> }),
+];
+export default function App() {
+  return <Router routes={routes} />;
+}
+```
+## Step 7: Delete Unnecessary Files
+After migration, you can remove:
+- `src/main.tsx` (or `src/index.tsx`) - no longer needed
+- `index.html` - replaced by `Root.tsx`
+## Common Migration Patterns
+### Global Styles
+Import global CSS in your `App.tsx`:
+```tsx
+// src/App.tsx
+import "./index.css";
+import "./global.css";
+export default function App() {
+  // ...
+}
+```
+### Context Providers
+Wrap client-side providers in a client component:
+```tsx
+// src/Providers.tsx
+"use client";
+import { ThemeProvider } from "./ThemeContext";
+import { AuthProvider } from "./AuthContext";
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider>
+      <AuthProvider>{children}</AuthProvider>
+    </ThemeProvider>
+  );
+}
+```
+```tsx
+// src/App.tsx
+import { Providers } from "./Providers";
+import { HomePage } from "./pages/HomePage";
+export default function App() {
+  return (
+    <Providers>
+      <HomePage />
+    </Providers>
+  );
+}
+```
+### Environment Variables
+Client-side environment variables still work the same way with the `VITE_` prefix:
+```tsx
+// In client components
+const apiUrl = import.meta.env.VITE_API_URL;
+```
+## Verifying the Migration
+Run the development server:
+```bash
+npm run dev
+```
+Check that:
+- Your app loads correctly
+- Interactive components work (clicks, form inputs, etc.)
+- Routing works as expected
+- Styles are applied correctly
+Build for production:
+```bash
+npm run build
+```
+Your static files will be generated in `dist/public`, ready for deployment.
+## Troubleshooting
+### "Cannot use hooks in Server Component"
+Add `"use client"` at the top of components that use React hooks.
+### "window is not defined"
+Components using browser APIs must be client components. Add `"use client"` directive.
+### Styles not loading
+Ensure CSS imports are in `App.tsx` or in client components that are actually rendered.
+## What's Next?
+- Learn about [defer()](/funstack-static/api/defer) for code splitting Server Components
+- Explore [Optimizing RSC Payloads](/funstack-static/learn/optimizing-payloads) for better performance
+- Understand [How It Works](/funstack-static/learn/how-it-works) under the hood

package/dist/docs/index.md CHANGED Viewed

@@ -6,6 +6,7 @@ A Vite plugin for building static sites with React Server Components.
 - [FAQ](./FAQ.md) - This is a bug in React itself. Please wait for [the fix](https://github.com/facebook/react/pull/34760) to be released.
 - [Getting Started](./GettingStarted.md) - Welcome to **FUNSTACK Static**! Build high-performance Single Page Applications powered by React Server Components - no server required at runtime.
+- [Migrating from Vite SPA](./MigratingFromViteSPA.md) - Already have a Vite-powered React SPA? This guide walks you through migrating to FUNSTACK Static to unlock React Server Components and improved performance.
 ### API
@@ -15,6 +16,7 @@ A Vite plugin for building static sites with React Server Components.
 ### Learn
 - [How It Works](./learn/HowItWorks.md) - FUNSTACK Static is a React framework that leverages React Server Components (RSC) to build a fully static Single Page Application. The result is a set of files that can be deployed to **any static file hosting service** - no server required at runtime.
+- [Using lazy() in Server Components](./learn/LazyServerComponents.md) - React's `lazy()` API is typically associated with client-side code splitting. However, it can also be used in server environments to reduce the initial response time of the development server by deferring the work needed to compute your application.
 - [Optimizing RSC Payloads](./learn/OptimizingPayloads.md) - FUNSTACK Static uses React Server Components (RSC) to pre-render your application at build time. By default, all content is bundled into a single RSC payload. This page explains how to split that payload into smaller chunks for better loading performance.
 - [React Server Components](./learn/RSC.md) - [React Server Components (RSC)](https://react.dev/reference/rsc/server-components) are a new paradigm for building React applications where components can run on the server (or at build time) rather than in the browser.
 - [Server-Side Rendering](./learn/SSR.md) - In FUNSTACK Static, **Server-Side Rendering (SSR)** means a build-time process that pre-renders your React components (including client components) to HTML. This can make the initial paint faster.

package/dist/docs/learn/LazyServerComponents.md ADDED Viewed

@@ -0,0 +1,120 @@
+# Using lazy() in Server Components
+React's `lazy()` API is typically associated with client-side code splitting. However, it can also be used in server environments to reduce the initial response time of the development server by deferring the work needed to compute your application.
+## The Problem: Development Server Latency
+When the development server receives a request, it needs to compute `<App />` to generate the response. This computation requires loading all imported modules, even those for contents that are not needed for the current request. For example, consider a routing setup like this:
+```tsx
+// All these imports are loaded immediately
+import HomePage from "./pages/Home";
+import AboutPage from "./pages/About";
+import DocsPage from "./pages/Docs";
+import SettingsPage from "./pages/Settings";
+// ... more page imports
+const routes = [
+  route({ path: "/", component: defer(<HomePage />) }),
+  route({ path: "/about", component: defer(<AboutPage />) }),
+  // ... more routes
+];
+export default function App() {
+  return <Router routes={routes} />;
+}
+```
+In a large application with many routes, this upfront loading adds latency to the first request, even though only one route's component will actually render.
+While use of [defer()](./optimizing-payloads) helps reducing initial load by deferring _rendering_ of route components, the work to _import_ those components still happens immediately.
+## How lazy() Helps
+`lazy()` defers the import of a module until the component is actually rendered. In a server environment, this means:
+1. The initial `<App />` computation only loads the routing structure
+2. Page components are loaded on-demand when their route matches
+3. Unused route components are never loaded for that request
+```tsx
+import { lazy } from "react";
+// These imports are deferred
+const HomePage = lazy(() => import("./pages/Home"));
+const AboutPage = lazy(() => import("./pages/About"));
+const DocsPage = lazy(() => import("./pages/Docs"));
+const SettingsPage = lazy(() => import("./pages/Settings"));
+const routes = [
+  route({ path: "/", component: defer(<HomePage />) }),
+  route({ path: "/about", component: defer(<AboutPage />) }),
+  // ... more routes
+];
+```
+When a user visits `/about`, only `AboutPage` is actually imported. The other page modules remain unloaded, reducing the work the server needs to do.
+## Combining with `defer()`
+To use `lazy()` effectively in server components, you should combine it with `defer()`.
+Without `defer()`, the contents of the lazy-loaded components would be part of the initial RSC payload. This means the server would still need to fully render them before sending the response, negating the benefits of lazy loading.
+## Example
+Here's a complete example of using `lazy()` with FUNSTACK Router as a router library:
+```tsx
+import { lazy, Suspense } from "react";
+import { Outlet } from "@funstack/router";
+import { route } from "@funstack/router/server";
+import { defer } from "@funstack/static/server";
+import { Layout } from "./components/Layout";
+// Lazy load page components
+const HomePage = lazy(() => import("./pages/Home"));
+const AboutPage = lazy(() => import("./pages/About"));
+const DocsPage = lazy(() => import("./pages/Docs"));
+const routes = [
+  route({
+    path: "/",
+    component: (
+      <Layout>
+        <Outlet />
+      </Layout>
+    ),
+    children: [
+      route({
+        path: "/",
+        component: defer(<HomePage />),
+      }),
+      route({
+        path: "/about",
+        component: defer(<AboutPage />),
+      }),
+      route({
+        path: "/docs",
+        component: defer(<DocsPage />),
+      }),
+    ],
+  }),
+];
+```
+## When to Use This Pattern
+This optimization is most beneficial when:
+- **You have many routes** - The more unused routes you can skip loading, the bigger the win
+- **Page components have heavy dependencies** - If a page imports large libraries, deferring that import saves significant work
+- **Development server responsiveness matters** - This pattern primarily improves development experience; production builds pre-render everything anyway
+For small applications with few routes, the overhead of `lazy()` may not be worth it. But as your application grows, lazy loading routes becomes increasingly valuable.
+## See Also
+- [Optimizing RSC Payloads](/funstack-static/learn/optimizing-payloads) - Using `defer()` to split RSC payloads
+- [How It Works](/funstack-static/learn/how-it-works) - Overall FUNSTACK Static architecture
+- [defer()](/funstack-static/api/defer) - API reference for the defer function

package/dist/docs/learn/OptimizingPayloads.md CHANGED Viewed

@@ -98,6 +98,8 @@ Each payload file has a **content-based hash** in its filename. This enables agg
 **Consider below-the-fold content** - Content hidden in collapsed sections, tabs, or modals is a good candidate for `defer()` since users may never need it.
+> **Tip:** You can combine `defer()` with React 19's `<Activity>` component to prefetch content in the background. When a `defer()`ed node is rendered under `<Activity mode="hidden">`, it won't be shown in the UI, but the fetch of the RSC payload will start immediately. This is useful when hidden content (like inactive tabs or collapsed sections) should be fetched ahead of time so it's ready when the user needs it.
 ## See Also
 - [defer()](/funstack-static/api/defer) - API reference with full signature and technical details

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@funstack/static",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "FUNSTACK static library",
   "type": "module",
   "repository": {