Migrating from 0.1.x

Most conventional 0.1.x themes will work on 0.2.x with a few minor tweaks.

Migration guide

Follow these steps to migrate a 0.1.x theme to 0.2.x:

• Update SALVO-TS:
  • npm install --save @eastsideco/salvo-ts@0.2 @eastsideco/salov-ts-build@0.2
• Upgrade TS and Sass:
  • npm install --save typescript@5.1.3 sass@1.63.3
• Update tsconfig.json:
  • Change target to "ES2016"
  • Change lib to "es2020"
• Delete the following lines:

  src/main.ts
  ts
  registerComponents(require.context('./components/', true), process.env.SALVO_BUILD_VARIANT);

  src/main.ts
  ts
  registerComponents(require.context('./components/', true), process.env.SALVO_BUILD_VARIANT);

  src/utils/formatting
  ts
  export * from '@eastsideco/salvo-ts/lib/imports/formatting';

  src/utils/formatting
  ts
  export * from '@eastsideco/salvo-ts/lib/imports/formatting';

SALVO-TS is now updated, but there are probably some other changes you need to make to finish upgrading:

• *SCSS

  • Sass has been updated and no longer supports implicit math without calc() in interpolations:

    Deprecated
    scss
    min-width: #{$size-container + $spacing-border};

    Deprecated
    scss
    min-width: #{$size-container + $spacing-border};

    Replacement
    scss
    min-width: #{calc($size-container + $spacing-border)};

    Replacement
    scss
    min-width: #{calc($size-container + $spacing-border)};

  • Sass has been updated and no longer supports implicit conversion between unitless and unit values:

    Deprecated
    scss
    $size-container: 500px;
    min-width: #{calc($size-container + 1)}; // 500px + 1
    max-width: #{calc($size-container * 2px)}; // 500px * 2px

    Deprecated
    scss
    $size-container: 500px;
    min-width: #{calc($size-container + 1)}; // 500px + 1
    max-width: #{calc($size-container * 2px)}; // 500px * 2px

    Replacement
    scss
    $size-container: 500px;
    min-width: #{calc($size-container + 1px)}; // 500px + 1px
    max-width: #{calc($size-container * 2)}; // 500px * 2

    Replacement
    scss
    $size-container: 500px;
    min-width: #{calc($size-container + 1px)}; // 500px + 1px
    max-width: #{calc($size-container * 2)}; // 500px * 2

• Decorators

  • Decorators must be static and resolvable at build-time, including default values. Move any runtime logic from your decorators into your component constructor or init:

    Unsupported
    ts
    @Prop({ default: window.pageYOffset }) scrollPosition!: number;

    Unsupported
    ts
    @Prop({ default: window.pageYOffset }) scrollPosition!: number;

    Replacement
    ts
    @Prop({ default: 0 }) scrollPosition!: number;
    init() {
        this.scrollPosition = window.pageYOffset;
    }

    Replacement
    ts
    @Prop({ default: 0 }) scrollPosition!: number;
    init() {
        this.scrollPosition = window.pageYOffset;
    }

• Legacy components

  • Legacy components must be manually imported into `src/main.ts:

    src/main.ts
    ts
    import "./components/LegacyExample.js";

    src/main.ts
    ts
    import "./components/LegacyExample.js";

  • Support for legacy components will be removed soon. Update your legacy components to standard SALVO-TS components.

• CSS imports

  • To optimize loading, TS files should not import CSS files. Move your CSS imports into your SCSS:

    Unsupported: src/components/ExampleComponent.ts
    ts
    import "mylib/foo.css";

    Unsupported: src/components/ExampleComponent.ts
    ts
    import "mylib/foo.css";

    Replacement: src/components/ExampleComponent.scss
    scss
    @import "mylib/foo.css";

    Replacement: src/components/ExampleComponent.scss
    scss
    @import "mylib/foo.css";

• Component structure

  • You must use a component's tag in it's template, or it's assets will not be loaded:

    Unsupported
    html
    <!-- Won't load any stylesheet because it doesn't refer to a component tag -->
    <ul class="navigation-breadcrumbs">
        <li>Foo</li>
    </ul>

    Unsupported
    html
    <!-- Won't load any stylesheet because it doesn't refer to a component tag -->
    <ul class="navigation-breadcrumbs">
        <li>Foo</li>
    </ul>

    Replacement
    html
    <!-- Will trigger NavigationBreadcrumbs.scss to load -->
    <navigation-breadcrumbs>
        <ul class="navigation-breadcrumbs">
            <li>Foo</li>
        </ul>
    </navigation-breadcrumbs>

    Replacement
    html
    <!-- Will trigger NavigationBreadcrumbs.scss to load -->
    <navigation-breadcrumbs>
        <ul class="navigation-breadcrumbs">
            <li>Foo</li>
        </ul>
    </navigation-breadcrumbs>

  • Component rules are more strictly required. This includes only exporting only one file per component, component names matching their filenames, and the other conventions which were previously advisory. Themes which follow the existing conventions should be fine, but you may need to move classes or rename files to match otherwise.