Vue 2 Integration

This guide covers integrating @esmx/router with Vue 2.7+. Vue 2.7 introduced built-in Composition API support, which @esmx/router-vue relies on for its composables.

Vue 2.7+ Required

@esmx/router-vue requires Vue 2.7 or later. Earlier versions of Vue 2 do not support the Composition API and are not compatible.

Installation

Install the core router and the Vue integration package:

npm install @esmx/router @esmx/router-vue

The same @esmx/router-vue package works with both Vue 2.7+ and Vue 3. It detects the Vue version automatically.

Differences from Vue 3

Before diving in, here are the key differences from the Vue 3 integration:

Aspect	Vue 3	Vue 2.7+
Plugin installation	`app.use(RouterPlugin)`	`Vue.use(RouterPlugin)`
App creation	`createApp()` / `createSSRApp()`	`new Vue()`
Mounting	`app.mount('#app')`	`new Vue().$mount('#app')`
SSR renderer	`@vue/server-renderer`	`vue-server-renderer`
Options API access	Works via `$router` / `$route`	Works via `$router` / `$route`
Composition API	`useRouter()` / `useRoute()`	`useRouter()` / `useRoute()`

The route definitions, composables, and components (RouterView, RouterLink) are identical.

Step-by-Step Setup

1. Define Your Routes

Same as Vue 3 — routes are framework-agnostic:

src/routes.ts

import type { RouteConfig } from '@esmx/router';

export const routes: RouteConfig[] = [
  {
    path: '/',
    component: () => import('./layouts/MainLayout.vue'),
    children: [
      { path: '', component: () => import('./pages/Home.vue') },
      { path: 'about', component: () => import('./pages/About.vue') },
      {
        path: 'users/:id',
        component: () => import('./pages/UserProfile.vue'),
        meta: { requiresAuth: true }
      }
    ]
  }
];

2. Create the App Factory

The main difference from Vue 3 is using new Vue() instead of createApp():

src/create-app.ts

import Vue from 'vue';
import { Router } from '@esmx/router';
import { RouterPlugin, useProvideRouter } from '@esmx/router-vue';
import App from './App.vue';

// Install the plugin globally (Vue 2 style)
Vue.use(RouterPlugin);

export function createVueApp(router: Router) {
  const app = new Vue({
    setup() {
      useProvideRouter(router);
      return () => (Vue as any).h(App);
    }
  });

  return { app, router };
}

Key differences from Vue 3:

Vue.use(RouterPlugin) is called on the Vue constructor, not on an app instance.
new Vue() replaces createApp() / createSSRApp().
useProvideRouter(router) works the same — it must be called inside setup().

3. Client Entry

src/entry.client.ts

import { Router, RouterMode } from '@esmx/router';
import { createVueApp } from './create-app';
import { routes } from './routes';

const router = new Router({
  root: '#app',
  mode: RouterMode.history,
  routes
});

const { app } = createVueApp(router);
app.$mount('#app');

Note: Vue 2 uses $mount() instead of mount().

4. Server Entry (SSR)

Vue 2 uses vue-server-renderer instead of @vue/server-renderer:

src/entry.server.ts

import type { RenderContext } from '@esmx/core';
import { createRenderer } from 'vue-server-renderer';
import { Router, RouterMode } from '@esmx/router';
import { createVueApp } from './create-app';
import { routes } from './routes';

const renderer = createRenderer();

export default async (rc: RenderContext) => {
  const router = new Router({
    mode: RouterMode.memory,
    base: new URL(rc.params.url, 'http://localhost'),
    routes
  });

  await router.replace(rc.params.url);

  const { app } = createVueApp(router);
  const html = await renderer.renderToString(app);

  rc.html = `<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    ${rc.preload()}
    ${rc.css()}
</head>
<body>
    <div id="app">${html}</div>
    ${rc.importmap()}
    ${rc.moduleEntry()}
    ${rc.modulePreload()}
</body>
</html>`;
};

5. Node Entry

Use createRspackVue2App instead of createRspackVue3App:

src/entry.node.ts

import http from 'node:http';
import type { EsmxOptions } from '@esmx/core';

export default {
  async devApp(esmx) {
    return import('@esmx/rspack-vue').then((m) =>
      m.createRspackVue2App(esmx)
    );
  },

  async server(esmx) {
    const server = http.createServer((req, res) => {
      esmx.middleware(req, res, async () => {
        const rc = await esmx.render({
          params: { url: req.url }
        });
        res.end(rc.html);
      });
    });

    server.listen(3000, () => {
      console.log('Server started: http://localhost:3000');
    });
  }
} satisfies EsmxOptions;

Using the Router in Components

Composition API (Recommended)

Vue 2.7+ supports <script setup> with the Composition API. The composables are identical to Vue 3:

src/pages/UserProfile.vue

<template>
  <div>
    <h1>User {{ route.params.id }}</h1>
    <p>Current path: {{ route.path }}</p>

    <button @click="goHome">Go Home</button>
  </div>
</template>

<script setup lang="ts">
import { useRouter, useRoute } from '@esmx/router-vue';
import { watch } from 'vue';

const router = useRouter();
const route = useRoute();

function goHome() {
  router.push('/');
}

watch(() => route.path, (newPath) => {
  console.log('Route changed to:', newPath);
});
</script>

Options API

The RouterPlugin makes this.$router and this.$route available in all components:

src/pages/About.vue

<template>
  <div>
    <h1>About</h1>
    <p>Current path: {{ $route.path }}</p>
    <button @click="navigateHome">Go Home</button>
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';

export default defineComponent({
  mounted() {
    console.log('Current route:', this.$route.path);
    console.log('Route params:', this.$route.params);
  },
  methods: {
    navigateHome() {
      this.$router.push('/');
    }
  }
});
</script>

RouterView and RouterLink

These work exactly the same as in Vue 3:

src/App.vue

<template>
  <div>
    <nav>
      <RouterLink to="/">Home</RouterLink>
      <RouterLink to="/about">About</RouterLink>
      <RouterLink to="/users/42">User 42</RouterLink>
    </nav>

    <RouterView />
  </div>
</template>

RouterLink supports the same props in both Vue 2 and Vue 3:

to — Target route (string or object)
type — Navigation type ('push', 'replace', 'pushWindow', etc.)
activeClass — CSS class when route matches
exact — Match mode ('include', 'exact', 'route')
tag — HTML tag to render (default: 'a')

Project File Structure

src/
├── entry.node.ts      # Node.js server setup, dev/build config
├── entry.server.ts    # SSR rendering logic
├── entry.client.ts    # Client-side hydration/mounting
├── create-app.ts      # Shared app factory
├── routes.ts          # Route definitions
├── App.vue            # Root component
├── layouts/
│   └── MainLayout.vue
└── pages/
    ├── Home.vue
    ├── About.vue
    └── UserProfile.vue

What's Next?

Dynamic Route Matching — Route parameters and patterns
Nested Routes — Layouts with child routes
Programmatic Navigation — All navigation methods
Navigation Guards — Intercept and control navigation

#Vue 2 Integration

#Installation

#Differences from Vue 3

#Step-by-Step Setup

#1. Define Your Routes

#2. Create the App Factory

#3. Client Entry

#4. Server Entry (SSR)

#5. Node Entry

#Using the Router in Components

#Composition API (Recommended)

#Options API

#RouterView and RouterLink

#Project File Structure

#What's Next?

#Vue 2 Integration

#Installation

#Differences from Vue 3

#Step-by-Step Setup

#1. Define Your Routes

#2. Create the App Factory

#3. Client Entry

#4. Server Entry (SSR)

#5. Node Entry

#Using the Router in Components

#Composition API (Recommended)

#Options API

#RouterView and RouterLink

#Project File Structure

#What's Next?

Vue 2 Integration

Installation

Differences from Vue 3

Step-by-Step Setup

1. Define Your Routes

2. Create the App Factory

3. Client Entry

4. Server Entry (SSR)

5. Node Entry

Using the Router in Components

Composition API (Recommended)

Options API

RouterView and RouterLink

Project File Structure

What's Next?

Vue 2 Integration

Installation

Differences from Vue 3

Step-by-Step Setup

1. Define Your Routes

2. Create the App Factory

3. Client Entry

4. Server Entry (SSR)

5. Node Entry

Using the Router in Components

Composition API (Recommended)

Options API

RouterView and RouterLink

Project File Structure

What's Next?