DEV Community

Manish Kumar
Manish Kumar

Posted on Edited on

Migrating Vue Router Configurations and Route Specs to TypeScript in GitLab Contributors Platform

As web applications expand in scope and team size, having type safety across routes, navigation guards, and route metadata becomes critical. Without types, a typo in a route name or malformed parameter props can lead to silent 404s and runtime navigation bugs that slip past linting.

In my recent contribution to GitLab's Contributors Platform (MR !3215), I converted the central application routing configuration (routes.js) and its comprehensive test suite (routes.spec.js) to strict TypeScript.

Here is an architectural walkthrough of how we typed our Vue Router 4 routing table, strengthened route metadata contracts, and tested route configurations.


1. Typing the Route Definitions with RouteRecordRaw

In a standard Vue 3 + Vue Router setup, route definitions are often exported as a loose JavaScript array:

// Before (routes.js)
export default [
  {
    name: 'dashboard',
    path: '/dashboard',
    component: DashboardPage,
  },
  // ...
];
Enter fullscreen mode Exit fullscreen mode

While functional, loose arrays do not catch misspelled route options, invalid meta shapes, or broken component imports during compilation.

By migrating to routes.ts, we bound the route collection to RouteRecordRaw[] from vue-router:

import type { RouteLocationNormalized, RouteRecordRaw } from 'vue-router';
import DocumentationPage from '~/pages/DocumentationPage.vue';

const routes: RouteRecordRaw[] = [
  {
    name: 'dashboard',
    path: '/dashboard',
    component: DashboardPage,
  },
  {
    name: 'documentation',
    path: '/docs/:page(.*)',
    component: DocumentationPage,
    props: (route: RouteLocationNormalized) => ({
      page: route.params.page || 'getting-started',
    }),
    meta: {
      title: "'Documentation',"
    },
  },
  // ...
];

export default routes;
Enter fullscreen mode Exit fullscreen mode

Key Improvements:

  • Strict Parameter Typing: Dynamic functional route props now take a typed RouteLocationNormalized parameter, ensuring route.params access is verified at compile time.
  • Route Record Validation: Misconfigured route properties (such as invalid regex patterns or misspelled lifecycle guards) are immediately highlighted by vue-tsc.

2. Strongly Typed Route Metadata Verification

In the GitLab Contributors platform, route metadata controls critical access policies, including:

  • Document title updates (meta.title)
  • Authentication barriers (meta.requireLogin)
  • Administrative authorization gates (meta.requireAdmin)

To prevent accidental regressions where a developer forgets to secure an administrative page or omits a title, the project runs a dedicated route metadata test suite.

During the TypeScript migration of routes.spec.ts, we eliminated untyped parameters and generic any casts:

import routes from './routes';

// Strongly typed predicate and sorting helper
const sortedRouteNames = (key: string, predicate: (val: unknown) => boolean) =>
  routes
    .filter(route => route.name != null)
    .filter(({ meta = {} }) => predicate(meta[key]))
    .map(route => route.name)
    .sort();

describe('meta.requireAdmin', () => {
  const adminRoutes = (isAdminRequired: boolean) =>
    sortedRouteNames('requireAdmin', requireAdmin =>
      isAdminRequired ? Boolean(requireAdmin) : !requireAdmin
    );

  it('contains the expected routes requiring admin privileges', () => {
    expect(adminRoutes(true)).toEqual([
      'admin',
      'admin-transcend-hackathon',
      'bonus-points',
      'user-edit',
    ]);
  });
});
Enter fullscreen mode Exit fullscreen mode

3. Aligning with ADR 006: Real Router in Specs

As established in ADR 006 (Real Router in Frontend Specs), test suites across the application do not rely on fragile route mocks or bare useRouter spies. Instead, they instantiate an isolated memory router via:

createTestRouter(location);
Enter fullscreen mode Exit fullscreen mode

Because routes.ts is now strictly typed, any spec mounting a component with createTestRouter immediately benefits from accurate routing resolution, correct path parameters, and query normalization matching production behavior.


Conclusion & Best Practices

  1. Type the Router Table: Always annotate route collections with RouteRecordRaw[]. It costs negligible effort and catches missing exports or bad component imports immediately.
  2. Lock Down Route Metadata: If route metadata (meta) powers authentication, permissions, or layout wrappers, enforce it through unit tests comparing sorted route lists.
  3. Zero any Discipline: Writing typed helper predicates ((val: unknown) => boolean) preserves TypeScript's safety guarantees without suppressing errors with @ts-ignore or any.

Check out the merged Merge Request on GitLab:

👉 GitLab Contributors MR !3215


Author: Manish Kumar

GitLab: @manishpatel00

Top comments (0)