@lightspeed/crane-api

Lightweight runtime API package for building custom sections and templates with @lightspeed/crane.

This package provides Vue 3 composables and TypeScript types needed for custom sections and templates, without CLI or build tools.

Installation

``bash
npm install @lightspeed/crane-api
`

> Note: This package is automatically included when using @lightspeed/crane. Install separately only if you need the API without the CLI.

Overview

The package exports:

- App Creation — createVueServerApp, createVueClientApp for SSR/hydration
- Content Composables — Access user-editable content (text, images, buttons, etc.)
- Design Composables — Access styling settings (colors, fonts, backgrounds)
- Types — TypeScript definitions for data structures

App Entry Points

Every section requires two entry points for SSR and client hydration:

`typescript
// server.ts — SSR rendering
import { createVueServerApp } from '@lightspeed/crane-api';
import Section from './Section.vue';
import type { ContentType, DesignType } from './type';

export default createVueServerApp(Section);
`

`typescript
// client.ts — Client hydration
import { createVueClientApp } from '@lightspeed/crane-api';
import Section from './Section.vue';
import type { ContentType, DesignType } from './type';

export default createVueClientApp(Section);
`

Content Composables

Access content defined in settings/content.ts:

| Composable | Editor Type | Return Type |
|------------|-------------|-------------|
| useInputboxElementContent | INPUTBOX | Reactive |
| useTextareaElementContent | TEXTAREA | Reactive |
| useButtonElementContent | BUTTON | Reactive |
| useImageElementContent | IMAGE | Reactive |
| useToggleElementContent | TOGGLE | Reactive |
| useSelectboxElementContent | SELECTBOX | Reactive |
| useDeckElementContent | DECK | Reactive |
| useCategorySelectorElementContent | CATEGORY_SELECTOR | Reactive |
| useProductSelectorElementContent | PRODUCT_SELECTOR | Reactive |
| useLogoElementContent | LOGO | Reactive |
| useMenuElementContent | MENU | Reactive |
| useNavigationMenuElementContent | NAVIGATION_MENU | Reactive |
| useTranslation | — | Translation helper |

$3

`typescript
import { useInputboxElementContent, useImageElementContent } from '@lightspeed/crane-api';
import type { ContentType } from './type';

const title = useInputboxElementContent('title');
const image = useImageElementContent('hero_image');

`

Design Composables

Access design settings defined in settings/design.ts:

| Composable | Editor Type | Return Type |
|------------|-------------|-------------|
| useTextElementDesign | TEXT | Reactive |
| useTextareaElementDesign | TEXTAREA | Reactive |
| useButtonElementDesign | BUTTON | Reactive |
| useBackgroundElementDesign | BACKGROUND | Reactive |
| useImageElementDesign | IMAGE | Reactive |
| useToggleElementDesign | TOGGLE | Reactive |
| useSelectboxElementDesign | SELECTBOX | Reactive |
| useLayoutElementDesign | — | Reactive |
| useLogoElementDesign | LOGO | ComputedRef |

$3

`typescript
import { useTextElementDesign, useBackgroundElementDesign } from '@lightspeed/crane-api';
import type { DesignType } from './type';

const titleStyle = useTextElementDesign('title_style');
const background = useBackgroundElementDesign('section_background');

`

Working with DECK

DECK allows collections of cards. Use getReactiveRef to access card fields:

`typescript
import { useDeckElementContent, EditorTypes } from '@lightspeed/crane-api';
import type { ContentType } from './type';

const slides = useDeckElementContent('slides');

slides.cards?.forEach(card => {
const title = slides.getReactiveRef(card, EditorTypes.INPUTBOX, 'title');
const image = slides.getReactiveRef(card, EditorTypes.IMAGE, 'background');
const button = slides.getReactiveRef(card, EditorTypes.BUTTON, 'cta');
});
``

Requirements

- Node.js >= 20
- Vue >= 3.4