Themes OctoberCMS Docs

Build your website using a familiar, file-based theme structure.

October CMS themes are file based. LAIKA preserves that foundation while combining October's server-side features with a Vue application built by Vite. Inspired by Inertia.js, LAIKA uses Vue single-file components for pages, layouts and partials, while keeping familiar October CMS concepts such as content blocks and components available where needed.

Difference to Classic Templating

Classic October templates separate configuration, PHP and Twig markup with ==. LAIKA places server-side configuration and PHP in <october> and <php> blocks, while the visible interface is written with Vue <template> and <script> blocks. The server-only blocks are removed before Vite compiles the component.

Directory Structure

A typical LAIKA theme looks like this:

themes/website/
├── theme.yaml
├── package.json
├── vite.config.ts
├── layouts/
│   └── Default.vue
├── pages/
│   └── Index.vue
├── partials/
│   └── site/
│       └── SiteFooter.vue
├── content/
│   └── welcome.md
├── resources/
│   ├── styles/
│   │   └── theme.css
│   └── theme.ts
└── assets/
    ├── images/
    │   └── logo.svg
    └── build/
        ├── .vite/
        │   └── manifest.json
        └── assets/
            ├── theme-[hash].js
            └── theme-[hash].css

Object	Description
Layouts	LAIKA components that provide shared structure around other components.
Pages	Route-level LAIKA components connected to October CMS pages and URLs.
Partials	Reusable LAIKA components shared by pages and layouts. Classic October .htm partials may also provide server-rendered fragments.
Content Files	Separately managed HTML, text, or Markdown content rendered by October CMS.
Resources	Source files processed by Vite, including the application entry point, styles, directives, and composables.
Assets	Public theme files such as images, together with the production files generated by Vite.

Pages, layouts and Vue partials are all LAIKA components. October CMS still handles routing, server lifecycle methods, October components, classic partials and content files. LAIKA connects both sides through the page payload and its runtime API.

The assets/build directory is generated by Vite and should not contain manually maintained source files. Files such as images that must remain directly accessible through October CMS belong in assets/images (or different subfolders within assets).

Vue Template Structure

A LAIKA component is a Vue single-file component with two optional server-side blocks:

<october>
url = "/"
title = "Home"
layout = "default"
</october>

<php>
function onStart(): void
{
    $this['heading'] = 'Welcome to LAIKA';
}
</php>

<template>
    <main>
        <h1>{{ heading }}</h1>
    </main>
</template>

<script lang="ts" setup>
defineProps<{
    heading: string;
}>();
</script>

The request still passes through October CMS first. October reads the configuration, runs the PHP lifecycle and prepares the page payload. LAIKA then mounts the matching Vue page and exposes the server values as page properties.

October Configuration

The <october> block uses the same INI-style configuration as a classic October template. A page can define values such as url, title, layout, description and component declarations. A layout can declare components and custom configuration in the same way.

<october>
url = "/articles/:slug"
title = "Article"
layout = "default"

[sitePicker]
</october>

These settings are evaluated by October CMS and are not included in the JavaScript bundle.

Server-side PHP

Use the <php> block for server lifecycle methods, AJAX handlers and values that must be prepared before the Vue application renders.

<php>
function onStart(): void
{
    $this['publishedAt'] = now()->toIso8601String();
}
</php>

Keep database access, authorization and secrets on the server. Only values placed in the LAIKA payload are available to the browser.

Vue Template and Script

The standard Vue sections work as they do in any Vue single-file component. You can use Composition API features, TypeScript, scoped styles and imports from the theme's resources directory.

<template>
    <p>{{ greeting }}</p>
</template>

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

const props = defineProps<{ name?: string }>();
const greeting = computed(() => `Hello ${props.name ?? 'visitor'}`);
</script>

<style scoped>
p {
    font-weight: 600;
}
</style>

Assets and Vite

The theme entry point normally lives at resources/theme.ts. Import client-side styles, register application plugins and start LAIKA from there. Files imported by Vue or TypeScript are processed by Vite; public build output belongs in the theme's configured asset directory.

Use October's asset helpers for server-rendered markup and ordinary Vite imports for assets consumed by Vue components.

Subdirectories

October CMS supports nested template paths, so pages, layouts, partials and content blocks can be grouped by feature. Refer to nested resources with a slash-separated name such as site/footer.

Keep paths predictable: route-level Vue files belong in pages, reusable client components and server-rendered fragments in partials.

Theme Logging

Code inside <php> runs in the October CMS request and can use the normal Laravel and October logging facilities. Browser-side Vue code should use browser tooling or send errors to an application error service. Do not expose server logs or sensitive exception details through the page payload.