@web-widget/vue

Web Widget supports file-system based routing conventions, automatically generating routemap.server.json during development.

File Naming Rules

Route Groups

Create route groups using parentheses-wrapped folder names:

└── routes
    ├── (middlewares)
    │   └── [...all]@middleware.ts # -> /:all*
    ├── (vue2)
    │   ├── package.json
    │   └── marketing@route.vue    # -> /marketing
    └── (vue3)
        ├── package.json
        └── info@route.vue         # -> /info

Basic Route Module

// ./routes/index@route.tsx
import { defineRouteComponent, defineMeta } from '@web-widget/helpers';
import BaseLayout from './components/BaseLayout';

export const meta = defineMeta({
  title: 'Home - Web Widget',
});

export default defineRouteComponent(function Page() {
  return (
    <BaseLayout>
      <h1>Welcome to Web Widget</h1>
      <p>This is a basic route module example</p>
    </BaseLayout>
  );
});

Data Fetching and Processing

// ./routes/fetch@route.tsx
import {
  defineRouteComponent,
  defineRouteHandler,
  defineMeta,
} from '@web-widget/helpers';
import BaseLayout from './components/BaseLayout';

interface PageData {
  items: Array<{ title: string; url: string }>;
}

async function fetchData(url: URL): Promise<PageData> {
  const response = await fetch(`${url.origin}/api/data`);
  return response.json();
}

export const meta = defineMeta({
  title: 'Data Fetching Example',
});

export const handler = defineRouteHandler<PageData>({
  async GET(ctx) {
    const data = await fetchData(new URL(ctx.request.url));

    const response = ctx.html(data);
    response.headers.set('X-Custom-Header', 'Hello');

    return response;
  },
});

export default defineRouteComponent<PageData>(function Page({ data }) {
  return (
    <BaseLayout>
      <h1>Data Fetching</h1>
      <ul>
        {data.items.map((item, index) => (
          <li key={index}>
            <a href={item.url}>{item.title}</a>
          </li>
        ))}
      </ul>
    </BaseLayout>
  );
});

Route Configuration

Routes are automatically configured based on your file structure. Web Widget generates the routing configuration during development, so you don't need to manually manage route mappings.

Dynamic Routes

// routes/users/[id]@route.tsx
export default defineRouteComponent(function UserPage(props) {
  const { id } = props.params;
  return <div>User ID: {id}</div>;
});

Navigation and Redirects

// Simple redirects in route handlers
export const handler = defineRouteHandler({
  async GET(ctx) {
    if (shouldRedirect) {
      return redirect('/new-path', 301);
    }
    return ctx.html();
  },
});

Error Handling

// Route-level error handling
export const handler = defineRouteHandler({
  async GET(ctx) {
    if (!data) {
      throw createHttpError(404, 'Not Found');
    }
    return ctx.html(data);
  },
});

Page Metadata Management

export const meta = defineMeta({
  title: 'My Page',
  description: 'Page description',
});

// Dynamic metadata in handlers
export const handler = defineRouteHandler({
  async GET(ctx) {
    const newMeta = mergeMeta(ctx.meta, {
      title: `User: ${user.name}`,
    });
    return ctx.html(null, { meta: newMeta });
  },
});

React Widget with Styles

// ./components/Counter@widget.tsx
import { useState } from 'react';
import styles from './Counter.module.css';

interface CounterProps {
  count: number;
}

export default function Counter(props: CounterProps) {
  const [count, setCount] = useState(props.count);

  return (
    <div className={styles.counter}>
      <button onClick={() => setCount(count - 1)}>−</button>
      <span className={styles.count}>{count}</span>
      <button onClick={() => setCount(count + 1)}>+</button>
    </div>
  );
}

Vue Widget with Scoped Styles

<!-- ./components/Counter@widget.vue -->
<script setup lang="ts">
import { ref } from 'vue';

interface CounterProps {
  count: number;
}

const props = defineProps<CounterProps>();
const count = ref(props.count);
</script>

<template>
  <div class="counter">
    <button @click="count--">−</button>
    <span class="count">{{ count }}</span>
    <button @click="count++">+</button>
  </div>
</template>

<style scoped>
/*...*/
</style>

Using Widgets in Routes

// ./routes/index@route.tsx
import { defineRouteComponent } from '@web-widget/helpers';
import BaseLayout from './components/BaseLayout';
import ReactCounter from './components/Counter@widget.tsx';
import VueCounter from './components/Counter@widget.vue';

export default defineRouteComponent(function Page() {
  return (
    <BaseLayout>
      <h1>Mixed Technology Stack Example</h1>

      <h2>React Component:</h2>
      <ReactCounter count={0} />

      <h2>Vue Component:</h2>
      <VueCounter count={0} />
    </BaseLayout>
  );
});

Render Control

// Server-only rendering
<StaticChart widget={{ serverOnly: true }} data={chartData} />

// Client-only rendering
<InteractiveMap widget={{ clientOnly: true }} location={coords} />

Working with Context

Access request data, parameters, and state in your components:

import { context } from '@web-widget/helpers/context';

export default function MyComponent() {
  const { request, params, state } = context();
  return <div>Current URL: {request.url}</div>;
}

Full Web Standards support in all environments:

• Network: fetch, Request, Response, Headers, WebSocket
• Encoding: TextDecoder, TextEncoder, atob, btoa
• Streams: ReadableStream, WritableStream, TransformStream
• Crypto: crypto, CryptoKey, SubtleCrypto
• Other: AbortController, URLPattern, structuredClone

Production-Ready Import Maps

{
  "imports": {
    "react": "https://esm.sh/react@18.2.0",
    "react-dom": "https://esm.sh/react-dom@18.2.0",
    "react-dom/client": "https://esm.sh/react-dom@18.2.0/client",
    "vue": "https://esm.sh/vue@3.4.8",
    "lodash": "https://esm.sh/lodash@4.17.21",
    "date-fns": "https://esm.sh/date-fns@2.30.0",
    "@company/ui-kit": "https://cdn.company.com/ui-kit@1.2.0/index.js",
    "@company/analytics": "https://cdn.company.com/analytics@2.1.0/index.js"
  },
  "scopes": {
    "/legacy/": {
      "react": "https://esm.sh/react@17.0.2",
      "react-dom": "https://esm.sh/react-dom@17.0.2"
    }
  }
}

Benefits in action:

• 📦 Automatic Deduplication: React loaded once, shared everywhere
• 🚀 CDN Optimization: Load popular libraries from fast CDNs
• 📱 Perfect Caching: Browser-native module caching

// In your components - just import naturally
import React from 'react'; // Shared via importmap
import { createApp } from 'vue'; // Shared via importmap
import MyComponent from '@components/MyComponent'; // Path mapping

// No build-time complexity, maximum runtime efficiency

The Web Platform Way: Instead of reinventing module sharing, we embrace the native solution that browsers are optimizing for.

Web Widget's Server Actions feature allows you to call server-side functions directly from client components with unprecedented simplicity - no API endpoints, no fetch calls, just direct function invocation.

🎯 The Revolution

// Traditional approach: Complex API setup
// ❌ Create API endpoint
export async function POST(request: Request) {
  const data = await request.json();
  return Response.json({ message: data.content, date: new Date() });
}

// ❌ Client-side fetch calls
const handleClick = async () => {
  const response = await fetch('/api/echo', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ content: inputValue }),
  });
  const result = await response.json();
  setLog(JSON.stringify(result));
};

// ✅ Web Widget Server Actions: Pure simplicity
// Server function (functions@action.ts)
export const echo = async (content: string) => {
  return {
    message: content,
    date: new Date().toISOString(),
    respondent: 'server',
  };
};

// Client component - call server function like any local function
const handleClick = async () => {
  const result = await echo(inputValue); // Direct server call!
  setLog(JSON.stringify(result));
};

🚀 Key Features

• 🎯 Direct Function Calls: Call server functions like local functions
• 📡 Automatic Networking: Framework handles HTTP requests/responses
• 🔒 Type Safety: End-to-end TypeScript support with full type checking
• ⚡ Zero Boilerplate: No API routes, no fetch calls, no serialization code
• 🌐 Environment Detection: Server functions automatically run server-side only

📁 File Structure

routes/action/
├── index@route.tsx        # Route page
├── Echo@widget.tsx        # Interactive client component
├── functions@action.ts    # Server-only functions
└── styles.css            # Styling

💻 Complete Example

// functions@action.ts - Server functions
export const echo = async (content: string) => {
  // This code ONLY runs on the server
  return {
    message: content,
    date: new Date().toISOString(),
    respondent: typeof document === 'undefined' ? 'server' : 'client',
  };
};

// Echo@widget.tsx - Client component
import { useState } from 'react';
import { echo } from './functions@action';

export default function EchoWidget() {
  const [inputValue, setInputValue] = useState('');
  const [result, setResult] = useState('');

  const handleSubmit = async () => {
    // Direct server function call - no fetch, no API endpoints!
    const response = await echo(inputValue);
    setResult(JSON.stringify(response, null, 2));
  };

  return (
    <>
      <input
        value={inputValue}
        onChange={(e) => setInputValue(e.target.value)}
      />
      <button onClick={handleSubmit}>Send to Server</button>
      {result && <pre>{result}</pre>}
    </>
  );
}

🌟 Why Server Actions Matter

1. 🎯 Simplicity: Write server logic as simple functions, not API endpoints
2. ⚡ Performance: Automatic request optimization and batching
3. 🔒 Security: Server functions never expose internals to client
4. 📱 Developer Experience: Unified development model across client/server
5. 🚀 Productivity: Focus on business logic, not infrastructure code

The Future of Full-Stack Development: Server Actions represent a paradigm shift from thinking in terms of "API endpoints" to thinking in terms of "server functions" - making full-stack development as natural as writing single-tier applications.

Web Widget provides enterprise-grade HTTP caching using standard Cache Control headers:

• Cache-Control: Standard max-age, stale-while-revalidate, stale-if-error
• ETag & Conditional Requests: Efficient cache validation
• Pluggable Storage: Memory, Redis, disk, or custom backends via SharedCache

// index@route.tsx

export const config = {
  cache: {
    // Cache rendered pages using HTTP cache control directives
    cacheControl: {
      // Cache for 60 seconds in shared caches
      sharedMaxAge: 60,
      // Serve stale content for 7 days on errors
      staleIfError: 604800,
      // Background revalidation for 7 days
      staleWhileRevalidate: 604800,
    },
  },
};

// ...

This mode requires integrating the @web-widget/middlewares/cache middleware

Complete Project Structure

my-web-widget-app/
├── routes/
│   ├── (components)/
│   │   ├── BaseLayout.tsx
│   │   ├── Counter@widget.tsx
│   │   └── Counter@widget.vue
│   ├── index@route.tsx
│   ├── about@route.tsx
│   ├── action/
│   │   ├── index@route.tsx
│   │   └── functions@action.ts
│   └── api/
│       └── hello@route.ts
├── public/
├── entry.client.ts
├── entry.server.ts
├── routemap.server.json
├── importmap.client.json
├── package.json
├── tsconfig.json
└── vite.config.ts

Package Dependencies

{
  "dependencies": {
    "@web-widget/helpers": "^3.0.0",
    "@web-widget/html": "^3.0.0",
    "@web-widget/node": "^3.0.0",
    "@web-widget/react": "^3.0.0",
    "@web-widget/vue": "^3.0.0",
    "@web-widget/web-router": "^3.0.0",
    "@web-widget/web-widget": "^3.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "vue": "^3.4.8"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^6.0.1",
    "@vitejs/plugin-vue": "^6.0.6",
    "@web-widget/vite-plugin": "^3.0.0",
    "vite": "^8.0.12"
  }
}

File Description

• routes/**/*@route.* Route modules that only run on the server side
• routes/**/*@middleware.* Middleware that only runs on the server side
• routes/**/*@action.* Server functions that can be called directly from client components
• routes/**/*@widget.* Components that can interact with users, running simultaneously on both server and client sides
• entry.client.ts Client entry point
• entry.server.ts Server entry point
• importmap.client.json Production module sharing configuration (used in builds only)
• routemap.server.json Routing configuration file, automatically generated by development tools

Development Best Practices

1. Technology Stack Isolation: Use widget modules to achieve isolation of different technology stack components
2. Progressive Enhancement: Prioritize server-side rendering, add client-side interaction as needed
3. Caching Strategy: Use lifecycle caching wisely to improve performance
4. Error Handling: Implement comprehensive error boundaries and fallback solutions
5. Type Safety: Make full use of TypeScript's type system

Performance Tips

• Use widget={{ serverOnly: true }} for static content that doesn't need interactivity
• Use widget={{ clientOnly: true }} for components that require browser APIs
• Implement proper caching strategies for expensive operations
• Keep server components lightweight to improve SSR performance

Code Organization

• Group related routes using parentheses folders
• Share common components through widget modules
• Use TypeScript interfaces for prop typing
• Implement proper error boundaries at route level