Miscellaneous

Shared Translations

Shared translations provide common static text that is available across all sections in your project. Use them for repeated phrases like "Read More", "Add to Cart", or other text shared between multiple sections.

Shared translations live in a single file at the project root:

shared/
└── translation.ts

The format is the same as section-level translations — a record keyed by language code:

// shared/translation.ts
export default {
  en: {
    '$label.shared.title': 'Title',
    '$label.shared.description': 'Description',
    '$label.shared.read_more': 'Read More',
  },
  fr: {
    '$label.shared.title': 'Titre',
    '$label.shared.description': 'Description',
    '$label.shared.read_more': 'Lire la suite',
  },
} as const;

💡 Convention

Use the $label.shared.* prefix for shared translation keys to distinguish them from section-specific keys.

Shared translations are automatically injected into every section at build time. Access them in your Vue components using the useTranslation composable:

<template>
  <a>{{ t('$label.shared.read_more') }}</a>
</template>

ℹ️ Hot Reload

Changes to shared/translation.ts trigger a full rebuild in preview mode.

Factory Methods

All configuration objects in Crane are created using factory functions from @lightspeed/crane-api. Factories accept a typed config object, auto-inject the type discriminator field, and return a fully typed result.

Factory	Purpose	Details
content	Content editor definitions	Content Editors
design	Design editor definitions	Design Editors
layout	Layout configurations and design overrides	Layout
showcase	Showcase configurations	Showcases
template	Template configuration and page definitions	Templates
section	Section references in pages (default, custom, store)	Templates — Pages
translation	Translation settings	Translations

The content and design factories also provide content.default.*() and design.default.*() sub-factories for creating standalone default values used in showcases.

import { content, design, layout, showcase, template, section, translation } from '@lightspeed/crane-api';

Linting

Crane provides @lightspeed/eslint-config-crane — a preconfigured ESLint setup for section development. The template scaffolds an eslint.config.cjs that consumes it as a one-liner:

// eslint.config.cjs
module.exports = require('@lightspeed/eslint-config-crane');

What It Includes

• Vue 3 — eslint-plugin-vue with recommended rules
• TypeScript — @vue/eslint-config-typescript recommended rules
• Scoped CSS — eslint-plugin-vue-scoped-css recommended rules
• Accessibility — eslint-plugin-vuejs-accessibility

Notable Rules

Rule	Setting	Description
vue/component-api-style	script-setup, composition	Only Composition API with <script setup> allowed
max-len	160	Maximum line length for .ts and .vue files
no-console	warn	Console statements produce warnings
no-debugger	warn	Debugger statements produce warnings

Running the Linter

The template does not include a lint script by default. Run ESLint directly:

npx eslint "./**/*.{js,ts}"

Or add a script to your package.json:

{
  "scripts": {
    "lint": "eslint \"./**/*.{js,ts}\""
  }
}

Advanced Composables

These composables are exported from @lightspeed/crane-api for advanced use cases. Most sections won't need them.

useVueBaseProps

Low-level composable providing reactive access to the full section context:

• context — store and environment information
• content — raw content data
• design — raw design data
• defaults — default values
• site — site configuration (languages, currency, etc.)
• category — current category data (on category pages)
• storeData — store metadata
• globalDesign — global design settings (colors, fonts, text sizes)
• tileId — the section's tile identifier

Use this when the typed content/design composables are not sufficient — for example, when accessing global design tokens directly or reading site-level configuration.

useInstantsiteJsApi

Returns window.instantsite — the platform's JavaScript API for interacting with the storefront runtime (e.g., triggering cart updates, navigation events).

import { useInstantsiteJsApi } from '@lightspeed/crane-api';

const api = useInstantsiteJsApi();

⚠️ Client-Only

This is a client-only API. Guard usage with typeof window !== 'undefined' or call it inside onMounted. See SSR vs Client-Only Rendering.