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

@funstack/static 0.0.2 → 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 (50) hide show

package/README.md +12 -3
package/dist/bin/skill-installer.d.mts +1 -0
package/dist/bin/skill-installer.mjs +12 -0
package/dist/bin/skill-installer.mjs.map +1 -0
package/dist/build/buildApp.mjs +4 -3
package/dist/build/buildApp.mjs.map +1 -1
package/dist/build/rscProcessor.mjs +9 -3
package/dist/build/rscProcessor.mjs.map +1 -1
package/dist/client/entry.d.mts +1 -0
package/dist/client/entry.mjs +17 -9
package/dist/client/entry.mjs.map +1 -1
package/dist/client/globals.mjs.map +1 -1
package/dist/docs/FAQ.md +5 -0
package/dist/docs/GettingStarted.md +180 -0
package/dist/docs/MigratingFromViteSPA.md +321 -0
package/dist/docs/api/Defer.md +110 -0
package/dist/docs/api/FunstackStatic.md +184 -0
package/dist/docs/index.md +22 -0
package/dist/docs/learn/HowItWorks.md +109 -0
package/dist/docs/learn/LazyServerComponents.md +120 -0
package/dist/docs/learn/OptimizingPayloads.md +107 -0
package/dist/docs/learn/RSC.md +179 -0
package/dist/docs/learn/SSR.md +104 -0
package/dist/entries/client.d.mts +1 -1
package/dist/entries/rsc-client.d.mts +2 -2
package/dist/entries/rsc-client.mjs +2 -2
package/dist/entries/server.d.mts +2 -2
package/dist/plugin/index.d.mts +17 -1
package/dist/plugin/index.d.mts.map +1 -1
package/dist/plugin/index.mjs +10 -1
package/dist/plugin/index.mjs.map +1 -1
package/dist/rsc/defer.d.mts +18 -3
package/dist/rsc/defer.d.mts.map +1 -1
package/dist/rsc/defer.mjs +34 -14
package/dist/rsc/defer.mjs.map +1 -1
package/dist/rsc/entry.d.mts.map +1 -1
package/dist/rsc/entry.mjs +85 -20
package/dist/rsc/entry.mjs.map +1 -1
package/dist/rsc-client/clientWrapper.d.mts +3 -3
package/dist/rsc-client/clientWrapper.d.mts.map +1 -1
package/dist/rsc-client/clientWrapper.mjs +2 -2
package/dist/rsc-client/clientWrapper.mjs.map +1 -1
package/dist/rsc-client/entry.d.mts +1 -1
package/dist/rsc-client/entry.mjs +1 -1
package/dist/ssr/entry.d.mts +2 -0
package/dist/ssr/entry.d.mts.map +1 -1
package/dist/ssr/entry.mjs +6 -2
package/dist/ssr/entry.mjs.map +1 -1
package/package.json +26 -11
package/skills/funstack-static-knowledge/SKILL.md +44 -0

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/api/Defer.md ADDED Viewed

@@ -0,0 +1,110 @@
+# defer()
+The `defer()` function enables deferred rendering for React Server Components, reducing initial data load.
+You can think of this as React's `lazy` API but for Server Components.
+## Import
+```typescript
+// @funstack/static/server is where utilities for server components live
+import { defer } from "@funstack/static/server";
+```
+## Usage
+```tsx
+import { defer } from "@funstack/static/server";
+import { HeavyServerComponent } from "./HeavyServerComponent";
+function Page() {
+  return (
+    <details>
+      <summary>Very long description</summary>
+      <Suspense fallback={<p>Loading...</p>}>
+        {defer(<HeavyServerComponent />)}
+      </Suspense>
+    </details>
+  );
+}
+```
+By using `defer()`, the `HeavyServerComponent` will still be rendered on the server (during build), but its data will be sent to the client as a separate RSC payload.
+This means that:
+- Client can start rendering the rest of the page without waiting for `HeavyServerComponent`'s data
+- When the `defer(<HeavyServerComponent />)` part is rendered on the client, it will fetch the separate RSC payload and show the content.
+The key point is that `HeavyServerComponent` is still a Server Component, so only the rendered HTML (and usage of Client Components inside it) is sent to the client, not the component code itself.
+**Note:** `defer()` must be used inside a `Suspense` boundary since the content will be streamed in later.
+## Signature
+```typescript
+export function defer(element: ReactElement, options?: DeferOptions): ReactNode;
+```
+### Parameters
+- **element:** A JSX element (Server Component) to render with deferred loading.
+- **options:** (optional) Configuration options for the deferred payload.
+### DeferOptions
+```typescript
+interface DeferOptions {
+  /**
+   * Optional name for debugging purposes.
+   * In development: included in the RSC payload file name.
+   * In production: logged when the payload file is emitted.
+   */
+  name?: string;
+}
+```
+- **name:** An optional identifier to help with debugging. When provided:
+  - In development mode, the name is included in the RSC payload file name (e.g., `/funstack__/fun:rsc-payload/HomePage-b5698be72eea3c37`)
+  - In production mode, the name is logged when the payload file is emitted
+### Returns
+A React Node that will stream its content separately from the main entry point.
+## When to Use defer()
+Use `defer()` when you have components that:
+- Renders large HTML content
+- Is not immediately visible on page load (e.g., inside a collapsed section)
+Typically, you will want to wrap route components with `defer()` to improve initial load performance. Otherwise, user needs to wait for contents for all pages to arrive before seeing anything.
+```tsx
+import { defer } from "@funstack/static/server";
+import HomePage from "./HomePage";
+import AboutPage from "./AboutPage";
+const routes = [
+  route({
+    path: "/",
+    component: defer(<HomePage />, { name: "HomePage" }),
+  }),
+  route({
+    path: "/about",
+    component: defer(<AboutPage />, { name: "AboutPage" }),
+  }),
+  // ...
+];
+```
+Using the `name` option makes it easier to identify which deferred component corresponds to which payload file during development and in build logs.
+## How It Works
+By default, FUNSTACK Static puts the entire app (`<App />`) into one RSC payload (`/funstack__/index.txt`). The client fetches this payload to render your SPA.
+When you use `defer(<Component />)`, FUNSTACK Static creates **additional RSC payloads** for the rendering result of the element. This results in an additional emit of RSC payload files like `/funstack__/fun:rsc-payload/b5698be72eea3c37`. If you provide a `name` option, the file name will include it (e.g., `/funstack__/fun:rsc-payload/HomePage-b5698be72eea3c37`).
+In the main RSC payload, the `defer` call is replaced with a client component `<DeferredComponent moduleId="fun:rsc-payload/b5698be72eea3c37" />`. This component is responsible for fetching the additional RSC payload from client and renders it when it's ready.

package/dist/docs/api/FunstackStatic.md ADDED Viewed

@@ -0,0 +1,184 @@
+# funstackStatic()
+The `funstackStatic()` function is the main Vite plugin that enables React Server Components for building SPAs without a runtime server.
+## Import
+```typescript
+import funstackStatic from "@funstack/static";
+```
+## Usage
+```typescript
+// vite.config.ts
+import funstackStatic from "@funstack/static";
+import { defineConfig } from "vite";
+export default defineConfig({
+  plugins: [
+    funstackStatic({
+      root: "./src/root.tsx",
+      app: "./src/App.tsx",
+    }),
+  ],
+});
+```
+## Options
+### root (required)
+**Type:** `string`
+Path to the root component file. This component wraps your entire application and defines the HTML document structure (`<html>`, `<head>`, `<body>`).
+```typescript
+funstackStatic({
+  root: "./src/root.tsx",
+  // ...
+});
+```
+The root component receives `children` as a prop:
+```tsx
+// src/root.tsx
+export default function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="UTF-8" />
+        <title>My Site</title>
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+### app (required)
+**Type:** `string`
+Path to the app component file. This component defines your application's content.
+```typescript
+funstackStatic({
+  root: "./src/root.tsx",
+  app: "./src/App.tsx",
+});
+```
+```tsx
+// src/App.tsx
+export default function App() {
+  return (
+    <div>
+      <h1>Welcome to My Site</h1>
+      {/* Your fantastic application goes here */}
+    </div>
+  );
+}
+```
+**Note:** if your app has multiple pages, you can use a routing library here just like in a traditional SPA.
+### publicOutDir (optional)
+**Type:** `string`
+**Default:** `"dist/public"`
+Output directory for the generated static files.
+```typescript
+funstackStatic({
+  root: "./src/root.tsx",
+  app: "./src/App.tsx",
+  publicOutDir: "build/static",
+});
+```
+### ssr (optional)
+**Type:** `boolean`
+**Default:** `false`
+Enable server-side rendering of the App component.
+When `false` (default), only the Root shell is rendered to HTML at build time. The App component's RSC payload is fetched separately and rendered client-side using `createRoot`. This results in faster initial HTML delivery but requires JavaScript to display the App content.
+When `true`, both the Root and App components are fully rendered to HTML. The client hydrates the existing HTML using `hydrateRoot`, which can improve perceived performance and SEO since the full content is visible before JavaScript loads.
+```typescript
+funstackStatic({
+  root: "./src/root.tsx",
+  app: "./src/App.tsx",
+  ssr: true, // Enable full SSR
+});
+```
+**Note:** In both modes, React Server Components are used - the `ssr` option only controls whether the App's HTML is pre-rendered or rendered client-side.
+### clientInit (optional)
+**Type:** `string`
+Path to a module that runs on the client side **before React hydration**. Use this for client-side instrumentation like Sentry, analytics, or feature flags.
+The module is imported for its side effects only - no exports are needed.
+```typescript
+funstackStatic({
+  root: "./src/root.tsx",
+  app: "./src/App.tsx",
+  clientInit: "./src/client-init.ts",
+});
+```
+Example client init file:
+```typescript
+// src/client-init.ts
+import * as Sentry from "@sentry/browser";
+Sentry.init({
+  dsn: "https://your-sentry-dsn",
+  environment: import.meta.env.MODE,
+});
+```
+**Note:** Errors in the client init module will propagate normally and prevent the app from rendering.
+## Full Example
+```typescript
+// vite.config.ts
+import { funstackStatic } from "@funstack/static";
+import { defineConfig } from "vite";
+export default defineConfig({
+  plugins: [
+    funstackStatic({
+      root: "./src/root.tsx",
+      app: "./src/App.tsx",
+      publicOutDir: "dist/public",
+    }),
+  ],
+});
+```
+## Vite Commands
+You can use the same Vite commands you would use in a normal Vite project:
+- `vite dev` - Starts the development server
+- `vite build` - Builds the static files
+- `vite preview` - Previews the built static files locally
+## See Also
+- [Getting Started](/funstack-static/getting-started) - Quick start guide
+- [defer()](/funstack-static/api/defer) - Deferred rendering for streaming
+- [React Server Components](/funstack-static/learn/rsc) - Understanding RSC

package/dist/docs/index.md ADDED Viewed

@@ -0,0 +1,22 @@
+# @funstack/static Documentation
+A Vite plugin for building static sites with React Server Components.
+## Available Documentation
+- [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
+- [defer()](./api/Defer.md) - The `defer()` function enables deferred rendering for React Server Components, reducing initial data load.
+- [funstackStatic()](./api/FunstackStatic.md) - The `funstackStatic()` function is the main Vite plugin that enables React Server Components for building SPAs without a runtime server.
+### 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.