Slots

Slots are custom Vue components that you can inject into a storefront layout. A layout can include any number of CUSTOM_SLOT placeholders, positioned anywhere in its template — letting you add custom UI at any point within product, catalog, or category pages.

layouts/
└── catalog/
    └── example-catalog/
        ├── Main.vue
        └── slots/
            └── custom-bottom-bar/
                ├── CustomBottomBar.vue
                ├── server.ts
                └── client.ts

Slots live inside the slots/ directory of a layout, organised by slot id. The slot id (directory name) is referenced in the layout's Main.vue via the slot-id attribute.

How Slots Work

A layout component uses the CUSTOM_SLOT slot name to define where custom content can appear. The slot-id attribute connects the placeholder to a specific slot directory.

Layout with a custom slot:

<template>
  <div>
    <slot :name="Slot.PRODUCT_LIST" />
    <slot :name="Slot.CUSTOM_SLOT" slot-id="custom-bottom-bar" />
  </div>
</template>

<script setup lang="ts">
import { CatalogLayoutSlot as Slot } from '@lightspeed/crane-api';
</script>

The slot-id="custom-bottom-bar" value must match a directory name under slots/ in the same layout.

The slot component itself is a regular Vue component, rendered both on the server (SSR) and on the client (hydration) — just like a section.

Slot component with entry points:

CustomBottomBar.vue

<template>
  <div class="custom-bottom-bar">
    <button @click="handleClick">
      Go to Account
    </button>
  </div>
</template>

<script setup lang="ts">
const handleClick = () => {
  // Custom client-side logic
};
</script>

server.ts

import { createVueServerApp } from '@lightspeed/crane-api';
import CustomBottomBar from './CustomBottomBar.vue';
import { Content, Design } from '../../type.ts';

export default createVueServerApp<Content, Design>(CustomBottomBar);

client.ts

import { createVueClientApp } from '@lightspeed/crane-api';
import CustomBottomBar from './CustomBottomBar.vue';
import { Content, Design } from '../../type.ts';

export default createVueClientApp<Content, Design>(CustomBottomBar);

ℹ️ Inherited settings

Slots inherit their content and design types from the parent layout's type.ts. The Content and Design types are imported from ../../type.ts relative to the slot directory.

Slot Files

Each slot directory must contain the following files:

File	Required	Description
Vue component (.vue)	Yes	The slot's UI component
server.ts	Yes	Server-side entry point using createVueServerApp
client.ts	Yes	Client-side entry point using createVueClientApp

Both entry points follow the same pattern as section entry points. Refer to the section documentation for details:

• Server entry point
• Client entry point

Connecting a Slot to a Layout

To add a custom slot to a layout:

1. Create a directory under slots/ in your layout (e.g. slots/my-widget/).
2. Add a Vue component, server.ts, and client.ts to the directory.
3. In the layout's Main.vue, use <slot :name="Slot.CUSTOM_SLOT" slot-id="my-widget" /> where the slot-id matches the directory name.

💡 Multiple slots

You can add multiple custom slots to a single layout by creating multiple directories under slots/ and referencing each one with a separate <slot> element using a different slot-id.

Validation Errors

Crane validates your slots during the build step. Below are the errors you may encounter and how to resolve them.

Slot Errors

Error	Cause	Resolution
Store layout sectionId "..." must be one of: catalog, category, product	Slot is placed under an invalid storefront page directory	Move the slot's parent layout under product/, catalog/, or category/
Size of individual server file [...] must not exceed threshold [...]	The slot's server bundle exceeds 500 KB (uncompressed)	Reduce the server bundle size — simplify the component or extract shared code
Cannot find client entrypoint file for slot ...	The slot directory is missing a client.ts file	Add a client.ts entry point to the slot directory

Schema Errors

Error	Cause	Resolution
Unrecognized key(s) in object	Extra properties in the slot configuration	Remove properties not defined in the schema

⚠️ Server Bundle Size Limit

Each slot's server bundle must not exceed 500 KB (uncompressed). Oversized bundles will cause a validation error during the build step.

Next Steps

• Learn about storefront layouts
• Learn about template pages
• Learn about template configuration