@itznotabug/routex

v0.0.3

Published

2 months ago

A client side redirection plugin for Vitepress.

Downloads

0High
0Medium
0Low

vitepress vitepress-plugin redirect redirects client-side-redirect vite-plugin typescript seo static-site url-redirect navigation documentation

Routex

A powerful client-side redirection plugin for VitePress that generates static redirect pages and handles seamless navigation between old and new URLs.

✨ Features

🔄 Client-side redirects - Fast, seamless navigation without server configuration
📄 Static redirect pages - Generates HTML files for each redirect during build
🎨 Custom templates - Use your own redirect page design or stick with the beautiful default
⚡ Zero JavaScript fallback - Works even with JavaScript disabled via meta refresh
🔍 SEO friendly - Proper meta tags, canonical links, and no-index options
🛡️ Validation - Detects circular redirects, conflicts, and dead links
⚙️ Flexible configuration - Simple redirect maps or advanced options

📦 Installation

pnpm add -D @itznotabug/routex

🚀 Quick Start

Add routex to your VitePress configuration:

// .vitepress/config.ts
import { routex } from 'routex'
import { defineConfig } from 'vitepress'

export default defineConfig({
    // ... your VitePress config
    vite: {
        plugins: [
            routex({
                '/old-page': '/new-page',
                '/legacy/docs': '/docs',
                '/api/v1': '/api/v2'
            })
        ]
    }
})

Routex will automatically:

Handle navigation seamlessly
Inject client-side redirect scripts
Generate redirect pages at build time

📖 Usage

Simple redirects

routex({
    '/old-page': '/new-page',
    '/legacy': '/modern',
    '/blog/2023': '/blog/archive/2023'
})

Advanced configuration

routex({
    rules: {
        '/old-api': '/api/v2',
        '/docs/legacy': '/docs',
        '/external-link': 'https://example.com'
    },
    options: {
        redirectDelay: 2,        // Delay in seconds (default: 0)
        addCanonical: true,      // Add canonical link tags (default: false)
        addNoIndexMeta: true,    // Add noindex meta tag (default: false)
        template: './custom-redirect.html',  // Custom template path
        overrideExisting: false, // Allow overriding existing pages (default: false)
        ignoreDeadLinks: false   // Skip validation for missing destinations (default: false)
    }
})

Custom Template

Create a custom redirect template with placeholders:

<!-- custom-redirect.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
      <meta charset="UTF-8">
      <title>Redirecting to {destination}</title>
      {metaTags}
      <style>
          body {
              font-family: system-ui;
              text-align: center;
              padding: 50px;
          }
      </style>
      <script>
          setTimeout(() => {
              location.replace('{destination}');
          }, {redirectDelay} * 1000);
      </script>
  </head>
  <body>
    <h1>🚀 Moving to a better place...</h1>
    <p>You're being redirected from <code>{source}</code> to <code>{destination}</code></p>
    <p><a href="{destination}">Click here if you're not redirected automatically</a></p>
  </body>
</html>

Available placeholders:

{source} - Original URL path
{destination} - Target URL
{redirectDelay} - Delay in seconds
{metaTags} - Generated meta tags (refresh, canonical, noindex)

⚙️ Configuration Options

| Option | Type | Default | Description | |--------------------|-----------|---------|-----------------------------------------------| | enable | boolean | true | Enable/disable the plugin | | redirectDelay | number | 0 | Delay before redirect (seconds) | | addCanonical | boolean | false | Add canonical link tags for SEO | | addNoIndexMeta | boolean | false | Add noindex meta tag to prevent indexing | | template | string | '' | Path to custom template or inline HTML | | overrideExisting | boolean | false | Allow redirects to override existing pages | | ignoreDeadLinks | boolean | false | Skip validation for missing destination pages |

🔍 Validation

Routex automatically validates your redirect configuration:

Self-references - Detects redirects that point to themselves
Circular redirects - Prevents infinite redirect loops
Path validation - Ensures proper URL formatting
File conflicts - Warns about redirects that override existing pages
Dead links - Checks if destination pages exist

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Ensure tests pass: pnpm test:run
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

🙏 Acknowledgments

Built for VitePress - The amazing static site generator
Continuous test releases via pkg-vc - Built by @Torsten Dittmann

⭐ Star this repo if you find it useful!