Skip to content

getting-started.md

Latest commit

 

History

History
186 lines (130 loc) · 4.18 KB

getting-started.md

File metadata and controls

186 lines (130 loc) · 4.18 KB

Getting Started

This guide walks you through setting up your first Structive component using a single-file component (SFC). You can choose between automatic or manual component registration.

1. Setup Import Map

Structive loads components via import() from HTML files. To resolve paths, define aliases using an import map.

Important: Always include the Structive framework itself with the alias structive:

Automatic Registration (Recommended)

Use the @components/ prefix for automatic component registration:

<script type="importmap">
{
  "imports": {
    "structive": "path/to/cdn/structive",
    "@components/my-component": "./components/my-component.html",
    "@components/another-component": "./components/another-component.html"
  }
}
</script>

Components with @components/ prefix are automatically registered as custom elements. The tag name will be the part after @components/ (e.g., @components/my-component becomes <my-component>).

Manual Registration

For manual control, use regular aliases:

<script type="importmap">
{
  "imports": {
    "structive": "path/to/cdn/structive",
    "my-component": "./components/my-component.html"
  }
}
</script>

🔍 Structive expects the component to be an HTML file containing <template>, <style>, and <script>.

Configuration (Optional)

If you don't need router functionality, you can disable it with configuration:

import { config } from "structive";

config.enableMainWrapper = false;
config.enableRouter = false;

💡 This configuration should be set before loading components or the autoloader.

2. Load Components

Automatic Registration

When using @components/ prefixed aliases, load the autoloader script:

<script type="module" src="path/to/cdn/autoloader"></script>

Components are then automatically registered. No additional JavaScript code needed!

📦 Multiple types of autoloaders are available based on config options. The appropriate loader will be selected automatically depending on your configuration settings.

Manual Registration

Use the defineComponents() function to register your components:

import { defineComponents } from "structive";

defineComponents({
  "my-component": "my-component"
});

This call:

  • fetches my-component.html
  • extracts its <template>, <style>, and <script> sections
  • registers <my-component> as a custom element

You can register multiple components at once:

defineComponents({
  "my-component": "my-component",
  "another-component": "another-component"
});

3. Create the Component

Save a file like components/my-component.html with the following contents:

<template>
  <p>{{ message }}</p>
</template>

<style>
p {
  font-weight: bold;
  color: darkcyan;
}
</style>

<script type="module">
export default class {
  message = "Hello from Structive!";
}
</script>

✅ Recommended order: template → style → script

4. Use the Component

In your HTML:

<body>
  <my-component></my-component>
</body>

Once the script runs and components are defined (automatically or manually), the content will render:

<p>Hello from Structive!</p>

Routing Components

For routing-enabled applications, use the @routes/ prefix:

<script type="importmap">
{
  "imports": {
    "structive": "path/to/cdn/structive",
    "@routes/home": "./pages/home.html",
    "@routes/about": "./pages/about.html"
  }
}
</script>

Components with @routes/ prefix are automatically registered as both components and routing paths (when router is enabled).

✅ That's it!

You've now:

  • Learned about automatic vs manual component registration
  • Defined a Structive single-file component
  • Registered it using importmap aliases
  • Rendered it using structure-only syntax

Recommendation: Use automatic registration with @components/ prefix for simpler setup and cleaner code.

Next steps:

  • Try using data-bind to bind attributes
  • Add getter to derive structured values
  • Explore structural loops and conditions in your template
  • Set up routing with @routes/ prefix

See Structure Philosophy for deeper insights!