@pagelume/component-sdk NPM

Pagelume Component SDK

Official SDK for building modular, reusable web components for the Pagelume platform.

Features

🎨 Component Templates - Pre-built templates for common component types
🎯 Handlebars Support - Full templating with custom helpers
💅 Global Styles - SCSS variables, mixins, and utility classes
📦 Vendor Scripts - Easy integration with popular libraries
⚡ Hot Reload - Instant preview updates with Vite
🔧 CLI Tools - Command-line tools for component management

Installation

npm install @pagelume/component-sdk

Quick Start

1. Choose Your Setup Location

Option A: Create a new project folder (recommended for new projects)

mkdir my-components
cd my-components

Option B: Use your current folder (if you're already in the right place)

# Just stay in your current directory - no need to create a subfolder

2. Initialize the Project

Run the init command to scaffold your project. This creates package.json and all necessary configuration files.

npx @pagelume/component-sdk init

Note: npx may prompt to install the package temporarily - this is normal. Type y to proceed. The package will be properly installed as a local dependency in step 3.

3. Install Dependencies

Install the required dependencies using npm.

npm install

4. Start the Development Server

Start the Vite development server to see your components.

npm run dev

Visit http://localhost:3000 to see your component gallery.

Component Structure

Each component follows this structure:

components/
├── [component-type]/
│   └── [variation-name]/
│       ├── index.html      # Handlebars template
│       ├── meta.json       # Component metadata
│       └── assets/
│           ├── css/        # Compiled CSS (auto-generated)
│           │   ├── styles.css      # Expanded CSS
│           │   └── styles.min.css  # Minified CSS (with --minify)
│           ├── scss/       # SCSS source files
│           │   └── styles.scss
│           ├── js/         # JavaScript files
│           │   ├── script.js       # Source JavaScript
│           │   └── script.min.js   # Minified JS (with --minify)
│           └── img/        # Images

Example meta.json

{
  "name": "Simple Hero",
  "type": "hero",
  "variation": "simple-hero",
  "description": "A basic hero section",
  "version": "1.0.0",
  "vendors": ["gsap"],
  "fields": [
    {
      "name": "title",
      "type": "text",
      "label": "Title",
      "default": "Welcome"
    },
    {
      "name": "subtitle",
      "type": "text",
      "label": "Subtitle",
      "default": "Build amazing components"
    }
  ]
}

Global Assets

SCSS Variables & Mixins

Import global styles in your component SCSS:

@import '@pagelume/sdk/global-assets/scss/variables';
@import '@pagelume/sdk/global-assets/scss/mixins';

.my-component {
  color: $primary;
  @include container;
  
  @include md-up {
    padding: $spacer * 2;
  }
}

Vendor Scripts

Add vendor dependencies using the data-pagelume-vendors attribute:

<div data-pagelume-vendors="jquery,slick">
  <!-- Your component -->
</div>

Available vendors (all bundled locally):

jquery - jQuery 3.7.1
bootstrap - Bootstrap 5.3.3
slick - Slick Carousel 1.8.1
gsap - GSAP Animation 3.12.5
gsapScrollTrigger - GSAP ScrollTrigger
aos - Animate On Scroll 2.3.4
swiper - Swiper.js 11.x
isotope - Isotope Layout 3.x
lightbox2 - Lightbox2 2.11.4

Handlebars Helpers

The SDK provides numerous custom Handlebars helpers:

Comparison Helpers

{{#if (eq value1 value2)}} - Equal
{{#if (ne value1 value2)}} - Not equal
{{#if (lt value1 value2)}} - Less than
{{#if (gt value1 value2)}} - Greater than
{{#if (and condition1 condition2)}} - Logical AND
{{#if (or condition1 condition2)}} - Logical OR

String Helpers

{{uppercase text}} - Convert to uppercase
{{lowercase text}} - Convert to lowercase
{{capitalize text}} - Capitalize first letter
{{truncate text 50}} - Truncate text
{{slugify text}} - Convert to URL slug

Array Helpers

{{length array}} - Get array length
{{first array}} - Get first item
{{last array}} - Get last item
{{join array ", "}} - Join array items

Math Helpers

{{add num1 num2}} - Addition
{{subtract num1 num2}} - Subtraction
{{multiply num1 num2}} - Multiplication
{{divide num1 num2}} - Division

CLI Commands

Initialize Project

npx @pagelume/component-sdk init

Create Component

npx @pagelume/component-sdk create

List Components

npx @pagelume/component-sdk list

Serve Components

npx @pagelume/component-sdk serve [--port 3000]

If you have the package installed locally, you can also use the shorter pagelume-cli command:

npm install @pagelume/component-sdk
pagelume-cli init
pagelume-cli create
pagelume-cli list
pagelume-cli serve

API Usage

ComponentBuilder

import { ComponentBuilder } from '@pagelume/component-sdk';

const builder = new ComponentBuilder({
  sourcePath: './components',
  outputPath: './dist'
});

const components = await builder.build();

ComponentRenderer

import { ComponentRenderer } from '@pagelume/component-sdk';

const renderer = new ComponentRenderer();
const html = renderer.render(component, {
  data: { title: 'Hello World' },
  inlineStyles: true,
  inlineScripts: true
});

Vite Plugin

// vite.config.js
import { VitePlugin } from '@pagelume/component-sdk';

export default {
  plugins: [
    VitePlugin({
      componentsDir: 'components',
      enableHMR: true
    })
  ]
};

Development

To work on the SDK itself:

# Clone the repository
git clone https://github.com/ImranBug/pagelume_component-sdk.git
cd component-sdk

# Install dependencies
npm install

# Build the SDK
npm run build

# Run in development mode
npm run dev

License

MIT

Support

For issues and feature requests, please visit our GitHub repository.

Asset Compilation & Build System

The SDK includes a powerful asset compilation system that automatically:

✅ Compiles SCSS to CSS with proper import resolution
✅ Minifies JavaScript using Terser (industry-standard)
✅ Minifies CSS with compressed output
✅ Generates source maps for debugging
✅ Watches for changes and rebuilds automatically
✅ Auto-builds on component creation

Build Commands

# Build all component assets
npm run build:components

# Build with minification (production-ready)
npm run build:components:min

# Build with minification and source maps
npm run build:components:prod

# Watch mode - rebuild on file changes
npm run build:components:watch

Or use the CLI directly:

# Basic build
pagelume-cli build

# Production build with all optimizations
pagelume-cli build --minify --source-map

# Watch mode for development
pagelume-cli build --watch

Automatic Building

On Creation: Components are automatically built when created
On Development: Use watch mode for live rebuilding
On Changes: Only modified components are rebuilt

What Gets Generated

When you run a build, the system generates:

your-component/
├── assets/
│   ├── css/
│   │   ├── styles.css      # 📝 Readable CSS from SCSS
│   │   └── styles.min.css  # 🗜️ Minified CSS (--minify)
│   ├── scss/
│   │   └── styles.scss     # 📝 Your source SCSS
│   └── js/
│       ├── script.js       # 📝 Your source JavaScript  
│       └── script.min.js   # 🗜️ Minified JS (--minify)

pagelume components sdk web-components handlebars