Creating components

First, start the compiler using npm run dev. This will watch for any changes and compile the updated theme into the dist/ folder.

Compiler output

Each time the compiler performs a build it'll output a file listing showing which dist files were updated and their size. The compiler will only write output files to dist/ when they have changed - if there were any unchangd files the compiler will show that on the last line.

All of the TS code for your theme lives inside the src/ folder. Inside this is also the special folder src/components, which is where you define components.

To create your first component, create a new file src/components/TabContainer.ts:

src/components/GreeterComponent.ts
ts
import { Component } from '@eastsideco/salvo-ts';
import { ThemeComponent } from '../theme/ThemeComponent';
@Component
export class GreeterComponent extends ThemeComponent {
}

src/components/GreeterComponent.ts
ts
import { Component } from '@eastsideco/salvo-ts';
import { ThemeComponent } from '../theme/ThemeComponent';
@Component
export class GreeterComponent extends ThemeComponent {
}

Let's break this down:

• @Component - This is a decorator which marks this class as a component. It's required on every component.
• export class GreeterComponent - This class represents the component we're making. We'll put the component's behavior and logic inside this class.
• extends ThemeComponent - This is the default base component in your theme. Anything you add to ThemeComponent will appear in all of your components. All of the components you create should extend ThemeComponent.

Using components

To use the new component in your theme, just add a HTML tag with a matching name - in this case <greeter-component>. Add this to static/sections/product-main.liquid (or your choice of snippet/section):

static/layout/theme.liquid
html
<greeter-component></greeter-component>

static/layout/theme.liquid
html
<greeter-component></greeter-component>

Component logic

By itself this component won't do anything, so let's add some logic using the init() hook, which runs when the component has been initialized and is present on the page:

src/components/GreeterComponent.ts
ts
@Component
export class GreeterComponent extends ThemeComponent {
    init() {
        this.$log.info('Hello from GreeterComponent!');
    }
}

src/components/GreeterComponent.ts
ts
@Component
export class GreeterComponent extends ThemeComponent {
    init() {
        this.$log.info('Hello from GreeterComponent!');
    }
}

Open your theme preview and go to the product page (or the page where you added the tag) and you should see Hello from GreeterComponent! in your devtools console.

Rules for components

When creating your own components in the future, it's important to stick to the following rules, or your components won't load correctly:

• Each .ts file in components/ must export exactly ONE component.
  • If you have multiple components, give each one it's own file.
• Each .ts file in components/ needs to be named the same as the component it exports.
  • For instance, a TabContainer.ts should export a class named TabContainer.
• If you are using a component from outside it's own file, you must import it. This includes finding a component using querySelector or getElementById.
  • If you don't do this then it's possible the component won't be loaded in the browser when you try to modify it or call a function on it.
  • See the cross-component manipulation example.
• Components may be organized in subfolders, but the name of the component must contain the subfolder as a prefix.
  • For example, components/Product/ProductForm is valid but components/Product/FeaturesBox is not. This helps find components more easily.

Next steps

Follow the rest of this tutorial to find out how to work with other assets in your themes, then check out the handbook to learn features which will let you use components more effectively, including component templates, and events.