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

@funstack/static 0.0.2 → 0.0.3

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 (48) hide show

package/README.md +12 -0
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/api/Defer.md +110 -0
package/dist/docs/api/FunstackStatic.md +184 -0
package/dist/docs/index.md +20 -0
package/dist/docs/learn/HowItWorks.md +109 -0
package/dist/docs/learn/OptimizingPayloads.md +105 -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/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,20 @@
+# @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.
+### 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.
+- [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/HowItWorks.md ADDED Viewed

@@ -0,0 +1,109 @@
+# How It Works
+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.
+FUNSTACK Static is built on top of [@vitejs/plugin-rsc](https://www.npmjs.com/package/@vitejs/plugin-rsc) for its RSC support.
+## Architecture
+FUNSTACK Static applications have **a single entrypoint** which is a server component. This component is responsible for rendering the entire application.
+```tsx
+// src/App.tsx
+export default function App() {
+  return (
+    <div>
+      <h1>Welcome to my FUNSTACK Static app!</h1>
+      {/* Your app components go here */}
+    </div>
+  );
+}
+```
+Currently, no routing solution is built in. If you need routing, you can use your favorite routing library for SPAs, such as [React Router](https://reactrouter.com/) (SPA mode) or [FUNSTACK Router](https://github.com/uhyo/funstack-router).
+Server components cannot have any client-side interactivity. To add interactivity, you can use client components. FUNSTACK Static follows [the standard React Server Components conventions](https://react.dev/reference/rsc/server-components#adding-interactivity-to-server-components) (`"use client"`) for defining client components.
+Behind the scenes, server components are rendered into **RSC payloads** at build time (or inside the development server in development mode). These payloads are then loaded by the client-side React application to reflect the server-rendered content to the DOM.
+On production mode builds, FUNSTACK Static generates a set of static files that include:
+- An `index.html` file that bootstraps the client-side React application
+- JavaScript files for the client-side React application and its dependencies
+- Asset files (CSS, images, etc.)
+- RSC payload files generated from server components
+Typically, the output structure looks like this:
+```
+dist/public
+├── assets
+│   ├── app-91R2BjDJ.css
+│   ├── app-CQU2Svmn.js
+│   ├── app-ovZqc1Hu.css
+│   ├── index-CCEDZan_.js
+│   ├── root-DvE5ENz2.css
+│   └── rsc-D0fjt5Ie.js
+├── funstack__
+│   └── fun:rsc-payload
+│       └── db1923b9b6507ab4.txt
+└── index.html
+```
+The RSC payload files under `funstack__` are loaded by the client-side code to bootstrap the application with server-rendered content.
+This can been seen as an **optimized version of traditional client-only SPAs**, where the entire application is bundled into JavaScript files. By using RSC, some of the rendering work is offloaded to the build time, resulting in smaller JavaScript bundles combined with RSC payloads that require less client-side processing (parsing is easier, no JavaScript execution needed).
+## Root Entry Point
+The root entry point of a FUNSTACK Static application is defined in the `funstack.config.js` file using the `root` option. This is a **special endpoint** that defines the HTML shell of your application. This is a separate endpoint from the main App component.
+A typical Root component looks like this:
+```tsx
+// src/Root.tsx
+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 FUNSTACK Static App</title>
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+The `children` prop contains the main App component.
+The Root component is special in two ways:
+1. Rendered into a fully static HTML file (`index.html`), not an RSC payload.
+2. Is **not hydrated** on the client side. This means that any client-side interactivity (e.g., event handlers) inside the Root component will not work.
+The Root entrypoint is a FUNSTACK Static counterpart to the `index.html` file in traditional SPAs. It allows you to still leverage some of the benefits of server components for defining the HTML shell of your application.
+## Server-Side Rendering
+By default, FUNSTACK Static only renders the Root shell to HTML. The App component is rendered client-side from its RSC payload. This behavior keeps the initial HTML small and fast to deliver.
+If you want the App component to also be rendered to HTML (for better SEO or perceived performance), you can enable the `ssr` option:
+```typescript
+funstackStatic({
+  root: "./src/root.tsx",
+  app: "./src/App.tsx",
+  ssr: true,
+});
+```
+With `ssr: true`, the full page content is visible in the HTML before JavaScript loads. The client then hydrates the existing HTML instead of rendering from scratch.
+Note that in both modes, React Server Components are still used - the `ssr` option only controls whether the App's HTML is pre-rendered at build time or rendered client-side.
+## See Also
+- [React Server Components](/funstack-static/learn/rsc) - Understanding RSC in depth
+- [Getting Started](/funstack-static/getting-started) - Set up your first project

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

@@ -0,0 +1,105 @@
+# Optimizing RSC Payloads
+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.
+## The Default Behavior
+Without any optimization, your entire application is rendered into one RSC payload file:
+```
+dist/public/funstack__/
+└── fun:rsc-payload/
+    └── b62ec6668fd49300.txt    ← Contains everything
+```
+This means users must download the entire payload before seeing any content - even if they only need one page of a multi-page application.
+**Note:** RSC payloads contain the rendering results of server components only; client components and their JavaScript bundles are handled separately. However, it is still important to optimize RSC payload sizes because the recommended best practice is to keep as much of your UI as server components as possible.
+## Chunking with defer()
+The `defer()` function lets you split your application into multiple RSC payloads. Each `defer()` call creates a separate payload file that loads on-demand when that component renders.
+```tsx
+import { defer } from "@funstack/static/server";
+// Instead of this:
+<HeavyContent />
+// Do this:
+<Suspense fallback={<p>Loading...</p>}>
+  {defer(<HeavyContent />)}
+</Suspense>
+```
+The content inside `defer()` is still rendered at build time, but it's stored in a separate file and fetched only when needed.
+**Note:** use of `defer()` requires a `<Suspense>` boundary to handle the loading state while the payload is being fetched.
+## Route-Level Optimization
+The most impactful use of `defer()` is wrapping your route components. This ensures users only download the payload for the page they're viewing:
+```tsx
+import { defer } from "@funstack/static/server";
+import { route } from "@funstack/router/server";
+import HomePage from "./pages/Home";
+import AboutPage from "./pages/About";
+import DocsPage from "./pages/Docs";
+const routes = [
+  route({
+    path: "/",
+    component: defer(<HomePage />),
+  }),
+  route({
+    path: "/about",
+    component: defer(<AboutPage />),
+  }),
+  route({
+    path: "/docs",
+    component: defer(<DocsPage />),
+  }),
+];
+```
+With this setup:
+- Visiting `/` only downloads the Home page payload
+- Navigating to `/about` fetches the About page payload on-demand
+- Users see content faster because they're not waiting for pages they haven't visited
+## Output Structure
+After building with route-level `defer()`, your output looks like this:
+```
+dist/public/funstack__/
+└── fun:rsc-payload/
+    ├── a3f2b1c9d8e7f6a5.txt ← Home page
+    ├── b5698be72eea3c37.txt ← About page
+    ├── b62ec6668fd49300.txt ← Main app shell
+    └── c7d8e9f0a1b2c3d4.txt ← Docs page
+```
+Each payload file has a **content-based hash** in its filename. This enables aggressive browser caching - the file only changes when its content changes.
+**Note:** during development, UUIDs are used instead of content hashes for faster rebuilds. Content hashes are applied during production builds.
+## Best Practices
+**Always wrap route components** - This is the single most important optimization. It prevents users from downloading content for pages they may never visit.
+**Use Suspense boundaries** - Every `defer()` call must be inside a `<Suspense>` boundary. The fallback is shown while the payload is being fetched.
+```tsx
+<Suspense fallback={<PageSkeleton />}>{defer(<PageContent />)}</Suspense>
+```
+**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.
+## See Also
+- [defer()](/funstack-static/api/defer) - API reference with full signature and technical details
+- [How It Works](/funstack-static/learn/how-it-works) - Overall FUNSTACK Static architecture
+- [React Server Components](/funstack-static/learn/rsc) - Understanding RSC fundamentals

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

@@ -0,0 +1,179 @@
+# React Server Components
+[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.
+## What Are Server Components?
+Server Components are React components that:
+- **Run on the server/build time** - Not in the browser
+- **Can be async** - Use `async/await` directly in components
+- **Have zero client bundle impact** - Their code never ships to the browser
+- **Can access server-side resources** - Files, databases, environment variables
+```tsx
+// This component runs at build time, not in the browser
+async function UserList() {
+  // Direct file system access
+  const data = await fs.readFile("./data/users.json", "utf-8");
+  const users = JSON.parse(data);
+  return (
+    <ul>
+      {users.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+## FUNSTACK Static and RSC
+FUNSTACK Static is a React framework **without a runtime server** that still leverages React Server Components to **improve performance of traditional SPAs**.
+All server components are rendered at **build time**, producing RSC Payloads that are fetched by the client (browser) at runtime.
+While dynamic server-side logic isn't possible with FUNSTACK Static, you can still benefit from RSC features like:
+- Reduced bundle size
+- Build-time data fetching
+- Async components
+```tsx
+// Build-time data fetching with an async Server Component
+async function BlogPost({ slug }: { slug: string }) {
+  // Runs during build, not at runtime
+  const content = await fetchMarkdownFile(`./posts/${slug}.md`);
+  return (
+    <article>
+      <Markdown content={content} />
+    </article>
+  );
+}
+```
+**Note:** in FUNSTACK Static, async data is fetched at build time. For truly dynamic data, you'll need client-side JavaScript and fetch data as you would do in pre-RSC SPAs.
+## Composing Server and Client Components
+While Server Components can't use hooks or browser APIs, they can render Client Components that do:
+```tsx
+// Server Component (runs at build time)
+async function ProductPage({ id }: { id: string }) {
+  const product = await fetchProduct(id);
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <p>{product.description}</p>
+      {/* Client Component for interactivity */}
+      <AddToCartButton productId={id} />
+    </div>
+  );
+}
+```
+```tsx
+// Client Component (runs in browser)
+"use client";
+import { useState } from "react";
+export function AddToCartButton({ productId }: { productId: string }) {
+  const [added, setAdded] = useState(false);
+  return (
+    <button onClick={() => setAdded(true)}>
+      {added ? "Added!" : "Add to Cart"}
+    </button>
+  );
+}
+```
+## Benefits for SPAs
+### 1. Reduced Bundle Size
+Unlike traditional SPAs where all code ships to the client, Server Components never reach the browser. Only static HTML (and glue code for client components) is sent.
+### 2. Reduced Warm-Up Time
+The browser does't need to execute Server Component code, leading to less JavaScript to parse and run on initial load. Only ship the code needed for interactivity.
+### 3. Build-Time Data Fetching
+Fetch data once at build time, embedded directly into your pre-rendered HTML:
+```tsx
+async function BlogIndex() {
+  // Fetched once during build, not on every page view
+  const posts = await fetchAllPosts();
+  return <PostList posts={posts} />;
+}
+```
+### 4. Full SPA Interactivity
+On the browser, your app behaves like any SPA - client-side navigation, state management, and all the interactivity you need:
+```tsx
+// Client Component for interactive features
+"use client";
+import { useState } from "react";
+import { useNavigate } from "@funstack/router";
+export function SearchBox() {
+  const [query, setQuery] = useState("");
+  const navigate = useNavigate();
+  return (
+    <input
+      value={query}
+      onChange={(e) => setQuery(e.target.value)}
+      onKeyDown={(e) => {
+        if (e.key === "Enter") {
+          navigate(`/search?q=${query}`);
+        }
+      }}
+    />
+  );
+}
+```
+### 5. Type-Safe Data Flow
+Data flows from Server Components to Client Components with full TypeScript support:
+```tsx
+interface Post {
+  id: string;
+  title: string;
+  content: string;
+}
+async function BlogPost({ slug }: { slug: string }): Promise<JSX.Element> {
+  const post: Post = await fetchPost(slug);
+  return <Article post={post} />;
+}
+```
+## Considerations
+When using FUNSTACK Static, keep in mind:
+1. **Build-time data** - Server Component data is fetched during build. For runtime data, use Client Components with standard fetch patterns.
+2. **No server context** - No access to cookies, headers, or request data in Server Components.
+3. **Only one entrypoint** - FUNSTACK Static apps are single-page applications, without any routing built in. All routing and navigation must be handled client-side.
+This makes FUNSTACK Static ideal for developers looking to leverage RSC benefits while deploying simple static SPAs without server infrastructure.
+## See Also
+- [Getting Started](/funstack-static/getting-started) - Set up your first project
+- [defer()](/funstack-static/api/defer) - Stream content progressively
+- [funstackStatic()](/funstack-static/api/funstack-static) - Plugin configuration