vite-plugin-solid-pages

0.4.3 verified Mon Apr 27 auth: no javascript

A Vite plugin for SolidJS that generates file-based routes for SPAs, following solid-start routing conventions. Version 0.4.3 is the latest stable release with no fixed release cadence (in-progress). Key differentiators: lightweight alternative to solid-start, provides virtual modules for routes and route info, supports lazy/eager loading, auto code-splits route config and component, and integrates with MDX and frontmatter.

Common errors

error Module not found: Can't resolve 'virtual:pages' in '...' ↓

cause Missing or incorrect TypeScript declarations for virtual modules.

fix

Add /// <reference types="vite-plugin-solid-pages/client" /> to your env.d.ts file.

error TypeError: Cannot read properties of undefined (reading 'forEach') ↓

cause routes from virtual:pages is undefined because the virtual module was not generated (e.g., no pages in configured directory).

fix

Ensure the pages directory (default src/pages) contains at least one route file with valid extension.

error Error: @solidjs/router is not installed ↓

cause Missing peer dependency @solidjs/router.

fix

Run 'pnpm add @solidjs/router' (version ^0.16.1).

error SyntaxError: Unexpected token 'export' ↓

cause ESM syntax used in a CommonJS context (e.g., using require() to import the plugin).

fix

Use ESM imports (import solidPages from ...). If you must use require(), use dynamic import: const solidPages = (await import('vite-plugin-solid-pages')).default

Warnings

gotcha The plugin uses virtual modules (virtual:pages, virtual:route-info) that are only available after the Vite dev server runs. TypeScript may complain about missing modules unless you add the provided env.d.ts declarations. ↓

fix Add the reference directive to your env.d.ts as shown in the quickstart.

deprecated SolidJS older versions may not be compatible. The plugin requires @solidjs/router ^0.16.1, which may differ from newer SolidJS versions. ↓

fix Ensure @solidjs/router version matches ^0.16.1.

gotcha The plugin is focused on SPA routing and does not support SSR or file-based layout like solid-start. Do not use for SSR projects. ↓

fix Use solid-start for SSR needs.

gotcha Route configuration using exported const in files may not be recognized if the export is not correctly defined. Ensure file exports follow the expected pattern (e.g., export const route = { ... }). ↓

fix Check documentation for the exact route config export syntax.

gotcha Eager loading mode may increase bundle size. Use lazy loading for production to enable code splitting. ↓

fix Set lazy: true in the plugin options or per route.

Install

npm install vite-plugin-solid-pages

yarn add vite-plugin-solid-pages

pnpm add vite-plugin-solid-pages

Imports

default

wrong

const solidPages = require('vite-plugin-solid-pages')

correct

import solidPages from 'vite-plugin-solid-pages'

ESM-only; CommonJS require will fail as the package has no default export in CJS

virtual:pages
wrong
```
import routes from 'vite-plugin-solid-pages/virtual:pages'
```
correct
```
import routes from 'virtual:pages'
```
virtual:pages is a virtual module, not a file path. It must be imported directly, without any prefix
virtual:route-info
wrong
```
import routeInfo from 'vite-plugin-solid-pages'
```
correct
```
import routeInfo from 'virtual:route-info'
```
virtual:route-info is a separate virtual module providing route metadata; do not import from the package itself

Quickstart

Sets up the Vite plugin with file-based routing from src/pages, includes TypeScript declarations, and mounts routes via @solidjs/router.

// vite.config.ts
import { defineConfig } from 'vite'
import solidPlugin from 'vite-plugin-solid'
import solidPages from 'vite-plugin-solid-pages'

export default defineConfig({
  plugins: [
    solidPlugin(),
    solidPages({
      dir: 'src/pages',
      extensions: ['tsx'],
    })
  ]
})

// src/env.d.ts
/// <reference types="vite/client" />
/// <reference types="vite-plugin-solid-pages/client" />

// src/index.tsx
import { Router } from '@solidjs/router'
import { render } from 'solid-js/web'
import routes from 'virtual:pages'

render(() => (
  <Router>
    {routes}
  </Router>
), document.getElementById('root')!)