Solid-Vue Adds Per-Page Layouts and Its First UI Kit Add-on: Octans UI

Solid-Vue is getting another small but important step toward making application structure easier to manage.

This release introduces two additions:

• Per-page layouts, powered by Vue Router's definePage().
• Octans UI add-on, our first integration with a UI component library.

They solve different problems, but they share the same goal: giving Solid-Vue applications more structure without making developers build and configure everything from scratch.

Per-Page Layouts

Not every page in an application should look the same.

A dashboard might need a persistent sidebar and navigation. An authentication page might need a simple centred card. A public page might use an entirely different shell.

Previously, developers had to decide how to structure those layouts themselves. Solid-Vue can now handle that part with a simple convention.

Create layout components inside src/layouts:

<!-- src/layouts/dashboard.vue -->
<template>
  <div class="dashboard-shell">
    <nav>
      <!-- Dashboard navigation -->
    </nav>

    <main>
      <slot />
    </main>
  </div>
</template>

You can also keep a default layout:

<!-- src/layouts/default.vue -->
<template>
  <main class="default-layout">
    <slot />
  </main>
</template>

Then wrap your application's router once in App.vue:

<script setup lang="ts">
import { SolidVueLayout } from 'solid-vue/client'
</script>

<template>
  <SolidVueLayout>
    <RouterView />
  </SolidVueLayout>
</template>

Individual pages can then request the layout they need:

<script setup lang="ts">
definePage({
  meta: {
    layout: 'dashboard',
  },
})
</script>

<template>
  <h1>Dashboard</h1>
</template>

That's it.

Pages that don't specify a layout automatically use src/layouts/default.vue.

This means layout selection stays close to the page itself instead of requiring another routing configuration file.

Why definePage()?

One important detail here is that definePage() isn't a Solid-Vue-specific API.

It comes from the Vue Router ecosystem and is already familiar to developers using file-based routing with Vue Router tooling.

Solid-Vue simply uses the page metadata to connect the route to the corresponding layout.

For example:

definePage({
  meta: {
    layout: 'auth',
  },
})

maps naturally to:

src/layouts/auth.vue

The convention keeps the amount of configuration small while still allowing applications to grow beyond a single application shell.

Layouts Are About More Than Visuals

A layout isn't necessarily just a collection of CSS classes.

It can represent an application's structural boundary.

For example, a typical application might eventually have:

src/
├── layouts/
│   ├── default.vue
│   ├── auth.vue
│   └── dashboard.vue
│
├── pages/
│   ├── index.vue
│   ├── login.vue
│   ├── register.vue
│   └── dashboard/
│       ├── index.vue
│       └── settings.vue

The pages remain focused on their own content, while layouts handle the surrounding application structure.

That separation becomes particularly useful when an application has several sections with different navigation, headers, or visual shells.

Our First UI Kit Add-on: Octans UI

The second addition in this release is a new Solid-Vue add-on for Octans UI.

Install it with:

npx solid-vue add octans-ui

This is the first time one of our add-ons integrates a UI component library rather than simply adding a development utility or configuration.

The goal is the same as with the rest of the Solid-Vue add-on system: reduce the amount of repetitive setup required when starting a project.

What Does the Add-on Do?

Octans UI requires a small amount of application-level setup.

The Solid-Vue add-on takes care of that wiring for you.

In particular, it:

1. Installs the required Octans UI package.
2. Adds the UiProvider integration to App.vue.
3. Registers the Octans UI plugin in main.ts.
4. Leaves the application ready to import and use Octans UI components.

For example:

<script setup lang="ts">
import { Button, Card } from '@octans/ui'
</script>

<template>
  <Card title="Hello">
    <Button primary>
      Click me
    </Button>
  </Card>
</template>

The important part isn't that installing a UI library is difficult.

It isn't.

The point is that these small integration steps are exactly the kind of setup that tends to get repeated across projects.

Solid-Vue's add-on system gives us a place to automate them.

We Don't Want the CLI to Guess

There is another detail we're particularly careful about.

A CLI that modifies an existing project needs to know when it can safely make an automatic change — and when it can't.

For example, the add-on can normally update App.vue and main.ts when they follow the expected structure.

But developers are free to customise those files.

If Solid-Vue can't confidently determine where an integration should be added, the add-on doesn't try to make a risky modification.

Instead, it reports what needs to be added manually.

That's intentional.

We'd rather give you a clear instruction than silently produce a broken application.

Using Layouts and Octans UI Together

These two features were also tested together.

A typical application can have a layout responsible for the application shell while Octans UI provides the components used inside it.

For example:

Application
│
├── SolidVueLayout
│   │
│   ├── Dashboard Layout
│   │   ├── Navigation
│   │   ├── Header
│   │   └── RouterView
│   │       │
│   │       └── Octans UI components
│   │
│   └── Other Layouts
│
└── Vue Router

The layout controls the surrounding structure.

The router controls which page is displayed.

Octans UI provides reusable interface components.

Each part has a relatively small responsibility, without requiring a large application architecture just to get started.

We tested this combination in both development and production builds, including a layout wrapping the UI provider and router.

The result is the same workflow you'd expect from a normal Solid-Vue application.

Getting Started

If you're starting a new project, create one with:

npm create solid-vue@latest my-app

Then:

cd my-app

And add Octans UI:

npx solid-vue add octans-ui

You can then create your layouts under:

src/layouts

and select them from individual pages with:

<script setup lang="ts">
definePage({
  meta: {
    layout: 'dashboard',
  },
})
</script>

What's Next?

We're keeping Solid-Vue's approach deliberately incremental.

Rather than adding every possible feature to the framework, we're looking for the repetitive pieces that developers commonly need when building small and growing applications.

Layouts are one of those pieces.

UI library integration is another.

The add-on system gives us room to experiment with more integrations without making every Solid-Vue project depend on everything.

And this is only the beginning of that approach.

Try It

Create a new Solid-Vue application:

npm create solid-vue@latest my-app
cd my-app

Then add Octans UI:

npx solid-vue add octans-ui

For more information, see the documentation:

• Routing — Layouts
• Add-ons

Solid-Vue is still in early access, so we'd love to hear what feels useful, what feels rough, and what you'd like to see next.

Try it, build something small, and let us know what you think.

See: Solid-Vue Adds Per-Page Layouts and Its First UI Kit Add-on: Octans UI