Webflow Router

A powerful client-side router designed specifically for Webflow sites, enabling smooth single-page application (SPA) navigation while maintaining Webflow's visual editor capabilities.

Features

• 🚀 Seamless Navigation: Enable SPA-like navigation in your Webflow site without page reloads
• 🎨 Webflow Compatible: Works with Webflow's visual editor and CMS
• 📦 File-based Routing: Organize your routes using a familiar file-based structure
• 🔄 Lifecycle Hooks: Manage component lifecycle with onMount and onDestroy hooks
• 🎭 Layout System: Support for nested layouts and shared UI components
• 🎯 Dynamic Routes: Handle dynamic parameters in your routes
• 🛠 TypeScript Support: Built with TypeScript for better developer experience
• ⚡ Performance: Optimized for fast page transitions

Quick Start

pnpx wfrouter@latest init

This will create a new project with the following structure:

pages/
├── +layout.ts        # Root layout
├── about/
│   └── +page.ts     # /about route
├── products/
│   ├── +layout.ts   # Layout for all product pages
│   └── [slug]/
│       └── +page.ts # /products/[slug] route

Installation

npm install webflow-router

Quick Start

1. Create your page modules in a structured format:

// pages/about/+page.ts
export default function AboutPage(globalData: any, params: RouteParams) {
  // Your page initialization logic
}

// Optional: Add lifecycle hooks
import { onMount, onDestroy } from "webflow-router";

onMount(() => {
  console.log("About page mounted");
  return () => {
    console.log("About page cleanup");
  };
});

2. Initialize the router:

import { WebflowRouter } from "webflow-router";
import { generatedRoutes } from "./generated-wf-routes";

const router = new WebflowRouter(generatedRoutes, import.meta.env.PROD); // Pass in your routes and production mode

router.start();

Route Structure

The router follows a file-based routing structure:

pages/
├── +layout.ts        # Root layout
├── about/
│   └── +page.ts     # /about route
├── products/
│   ├── +layout.ts   # Layout for all product pages
│   └── [slug]/
│       └── +page.ts # /products/[slug] route

Lifecycle Hooks

onMount

Register callbacks to run when a page or layout is mounted:

import { onMount } from "webflow-router";

onMount(() => {
  // Setup code
  return () => {
    // Cleanup code
  };
});

//or export a default function
export default function AboutPage() {
  // Your page initialization logic
}

onDestroy

Register callbacks to run when a page or layout is about to be destroyed:

import { onDestroy } from "webflow-router";

onDestroy(() => {
  // Cleanup code
});

Configuration Options

interface RouterOptions {
  baseDomain?: string; // Your Webflow site domain
  pageScriptBasePath?: string; // Base path for page scripts
  contentSelector?: string; // Selector for main content area
  headUpdateMode?: "selective" | "replace" | "none";
  globalData?: any; // Global data available to all pages
  baseHostedCSS?: string; // Base URL for CSS files
  enableLogs?: boolean; // Enable debug logging
  onNotFound?: (
    path: string,
    attemptedFetchUrl: string
  ) => Promise<void> | void;
  ignoreLinksSelector?: string; // Selector for links to ignore
  transformHtml?: (
    htmlString: string,
    path: string
  ) => string | Promise<string>;
  beforeLeave?: (
    currentRoute: MatchedRouteInfo | null,
    nextPath: string
  ) => Promise<boolean | void> | boolean | void;
  afterEnter?: (newRoute: MatchedRouteInfo) => Promise<void> | void;
}

Advanced Features

Layouts

Create shared layouts using +layout.ts files:

// pages/products/+layout.ts
export default function ProductsLayout(
  globalData: any,
  params: RouteParams,
  currentUrlPath: string
) {
  // Layout initialization logic
}

Dynamic Routes

Handle dynamic parameters in your routes:

// pages/products/[slug]/[slug2]+page.ts
import { onMount } from "webflow-router";

onMount(({ params: RouteParams }) => {
  const { slug, slug2 } = params;
  // Use the slug parameter
});

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - feel free to use this library in your projects.