Salla Twilight Bundles Starter Kit

This starter kit provides a foundation for building custom Twilight components for Salla's e-commerce platform. It includes a pre-configured build setup and development environment to help you get started quickly.

Getting Started

1. Clone this repository
2. Remove the example components in src/components/ using:

   tw-delete-component

3. Create your own components using the component generator:

   tw-create-component <component-name>

4. Run pnpm install to install dependencies
5. Run pnpm run dev to start the development server
6. Run pnpm run build to build your components for production

Project Structure

src/
  components/
    your-component-name/
      index.ts        # Main component file
      styles.ts       # Component styles (optional)
      types.ts        # Component types (optional)

Built-in Plugins

This starter kit includes three Vite plugins that handle the build process:

1. Transform Plugin (sallaTransformPlugin)

• Transforms component files to ensure proper naming and registration
• Matches components in src/components/*/index.ts
• To disable: Remove from vite.config.ts plugins array

2. Build Plugin (sallaBuildPlugin)

• Handles component bundling and output
• Creates individual files for each component in dist/
• Configures external dependencies (lit libraries)
• To customize: Remove from plugins array and configure your own build settings:

  {
    build: {
      lib: {
        entry: {/* your entries */},
        formats: ['es'],
        fileName: (format, entryName) => `${entryName}.js`
      },
      rollupOptions: {
        external: [/^lit/],
        output: {/* your output config */}
      }
    }
  }

3. Demo Plugin (sallaDemoPlugin)

• Provides a development environment for testing components
• Creates a demo page with your components
• Configures hot module reloading
• To disable: Remove from plugins array and set up your own dev server

Demo Plugin Options

The sallaDemoPlugin accepts the following configuration options:

{
  // Optional: Show only specific components
  components?: string[];

  // Optional: Customize the demo grid layout
  grid?: {
    // CSS grid-template-columns value
    columns?: string;     // default: 'repeat(auto-fill, minmax(300px, 1fr))'
    
    // Gap between components
    gap?: string;        // default: '1rem'
    
    // Responsive breakpoint
    minWidth?: string;   // default: '300px'
  };

  // Optional: Add custom CSS
  css?: string;

  // Optional: Add custom JavaScript
  js?: string;
}

Example Configuration

// vite.config.ts
export default defineConfig({
  plugins: [
    // ... other plugins
    sallaDemoPlugin({
      // Show only specific components
      components: ['product-card', 'scroll-top'],
      
      // Customize grid layout
      grid: {
        columns: 'repeat(3, 1fr)',
        gap: '1.5rem',
        minWidth: '768px'
      },

      // Add custom styles
      css: `
        .component-card {
          box-shadow: 0 2px 4px rgba(0,0,0,0.1);
          transition: transform 0.2s;
        }
        .component-card:hover {
          transform: translateY(-2px);
        }
      `,

      // Add custom JavaScript
      js: `
        console.log('Demo page loaded!');
        // Add your custom JavaScript here
      `
    })
  ]
});

Component Management

Creating New Components

This starter kit includes a component generator to help you create new components quickly. To use it, run:

tw-create-component <component-name>

Or run without arguments for interactive mode:

tw-create-component

The generator will:

1. Prompt you for a component name (in kebab-case format)
2. Validate that the name is in kebab-case and doesn't already exist
3. Create a new component folder with an index.ts file
4. Add the component definition to twilight-bundle.json

Deleting Components

To remove a component, use:

tw-delete-component <component-name>

Or run without arguments to see a list of available components:

tw-delete-component

This will:

1. Show a list of available components to select from
2. Ask for confirmation before deletion
3. Remove the component folder from src/components/
4. Remove the component definition from twilight-bundle.json

Component Requirements

Each component should:

1. Be a class that extends LitElement
2. Export the class as default
3. Be placed in its own directory under src/components/
4. Have an index.ts as the entry point

Example:

import { css, html, LitElement } from 'lit';
import { property } from 'lit/decorators.js';

export default class MyComponent extends LitElement {
  @property({ type: Object })
  config?: {
      title: string;
      // ... Add more properties as needed
  };
  

  static styles = css`/* your styles */`;

  render() {
    return html`<div>Hello ${this.config?.title || 'World'}!</div>`;
  }
}

Templates

A template is a saved arrangement of your components with their field values, stored as templates/<name>.json and registered in the templates array of twilight-bundle.json. The starter kit ships with one example template (templates/starter-template.json).

To create or update templates, use the demo page that opens with pnpm run dev:

1. Adjust your components' settings in the demo sidebar — values are the same ones stored in each component's fields in twilight-bundle.json
2. Save the current state as a template from the templates panel
3. The dev server writes templates/<name>.json (component list + field values) and updates twilight-bundle.json for you

You can also edit the template JSON files directly — each file contains the component objects with the value of every field.

Public Preview

Every saved template can get a shareable preview page — no npm publish, no public repo, and no hosting needed. Build, then publish a preview snapshot:

pnpm build
pnpm tw-preview

tw-preview uploads the bundle's templates and built components to Salla's preview service and prints a URL like:

https://salla.design/preview/s/<preview-id>/<template-name>

• Everything the build produced is included: component scripts, their shared chunks, and any media under dist/assets/ (images, fonts, video — up to 50MB per file). References like /assets/logo.svg are automatically repointed at the preview's own copies.
• The first publish authenticates with your Salla partner account — just be logged in via salla login (CI can set TW_PREVIEW_TOKEN instead).
• The preview id and its write key are saved to .salla-preview.json (auto-gitignored) — keep that file private. Re-running tw-preview after changes updates the same URL in place, no login needed.
• The URL is unguessable, so it's safe to share with clients even for private bundles.

Bundles that are published to npm under the @salla.sa scope also get automatic previews at https://salla.design/preview/<package-name>/<template-name> (pin a version with ?version=x.y.z).

Building for Production

Run pnpm run build to create production-ready bundles in the dist/ directory. Each component will have its own file named after the component (e.g., my-component.js).

Development

Run pnpm run dev to start the development server. This will:

1. Create a demo page with all your components
2. Enable hot module reloading
3. Provide a development environment for testing

License

MIT