Upgrading to Rindo v3.0.0

Getting Started

It's recommended that your projects start their upgrade from Rindo v2. Projects using Rindo v0 or Rindo v1 should upgrade to Rindo v2 before proceeding with this guide.

For projects that are on Rindo v2, install the latest version of Rindo v3: npm install @rindo/core@v3-next

Updating Your Code

New Configuration Defaults

Starting with Rindo v3.0.0, the default configuration values have changed for a few properties.

SourceMaps

Sourcemaps are generated by default for all builds. Previously, sourcemaps had to be explicitly enabled by setting the sourceMap flag to true. To restore the old behavior, set the sourceMap flag to false in your project's rindo.config.ts:

// rindo.config.ts
import { Config } from '@rindo/core';

export const config: Config = {
  sourceMap: false,
  // ...
};

dist-custom-elements Type Declarations

Type declaration files (.d.ts files) are now generated by default for the dist-custom-elements output target. If your project is using dist-custom-elements and you do not wish to generate type declarations, the old behavior can be achieved by setting generateTypeDeclarations to false in the dist-custom-elements output target in your project's rindo.config.ts:

// rindo.config.ts
import { Config } from '@rindo/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'dist-custom-elements',
      generateTypeDeclarations: false,
      // ...
    },
    // ...
  ],
  // ...
};

Legacy Browser Support Fields Deprecated

Several configuration options related to support for Safari <11, IE11, and Edge <19 have been marked as deprecated, and will be removed entirely in a future version of Rindo.

dynamicImportShim

The extras.dynamicImportShim option causes Rindo to include a polyfill for the dynamic import() function for use at runtime. The field is renamed to __deprecated__dynamicImportShim to indicate deprecation. To retain the previous behavior the new option can be set in your project's rindo.config.ts:

// rindo.config.ts
import { Config } from '@rindo/core';
export const config: Config = {
  extras: {
    __deprecated__dynamicImportShim: true,
  },
};

shadowDomShim

If extras.shadowDomShim is set to true the Rindo runtime will check whether a shim for shadow DOM is needed in the current browser, and include one if so. For Rindo v3.0.0 this field is renamed to __deprecated__shadowDomShim. To retain the previous behavior the new option can be set in your project's rindo.config.ts:

// rindo.config.ts
import { Config } from '@rindo/core';
export const config: Config = {
  extras: {
    __deprecated__shadowDomShim: true,
  },
};

cssVarsShim

extras.cssVarsShim causes Rindo to include a polyfill for CSS variables. For Rindo v3.0.0 this field is renamed to __deprecated__cssVarsShim. To retain the previous behavior the new option can be set in your project's rindo.config.ts:

// rindo.config.ts
import { Config } from '@rindo/core';
export const config: Config = {
  extras: {
    __deprecated__cssVarsShim: true,
  },
};

safari10

If extras.safari10 is set to true the Rindo runtime will patch ES module support for Safari 10. For Rindo v3.0.0 this field is renamed to __deprecated__safari10. To retain the previous behavior the new option can be set in your project's rindo.config.ts:

// rindo.config.ts
import { Config } from '@rindo/core';
export const config: Config = {
  extras: {
    __deprecated__safari10: true,
  },
};

Deprecated assetsDir Removed from @Component() decorator

The assetsDir field was deprecated in Rindo v2.0.0, but some backwards compatibility was retained with a warning message. It has been fully removed in Rindo v3.0.0 in favor of assetsDirs. To migrate from existing usages of assetsDir, update the property name and wrap its value in an array:

@Component({
  tag: 'my-component',
- assetsDir: 'assets',
+ assetsDirs: ['assets'],
})

For more information on the assetsDirs field, please see the Rindo Documentation on assetsDirs

Drop Node 12 Support

Rindo no longer supports Node 12. Please upgrade local development machines, continuous integration pipelines, etc. to use Node v14 or higher.

Strongly Typed Inputs

onInput and onInputCapture events have had their interface's updated to accept an argument of InputEvent over Event:

- onInput?: (event: Event) => void;
+ onInput?: (event: InputEvent) => void;
- onInputCapture?: (event: Event) => void;
+ onInputCapture?: (event: InputEvent) => void;

event arguments to either callback should be updated to take this narrower typing into account

Narrowed Typing for autocapitalize Attribute

The autocaptialize attribute has been narrowed from type any to type string. This change brings Rindo into closer alignment with TypeScript's typings for the attribute. No explicit changes are needed, unless a project was passing non-strings to the attribute.

Custom Types for Props and Events are now Exported from components.d.ts

Custom types for props and custom events are now re-exported from a project's components.d.ts file.

For the following Rindo component

import { Component, Event, EventEmitter, Prop, h } from '@rindo/core';

export type NameType = string;
export type Todo = Event;

@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true,
})
export class MyComponent {
  @Prop() first: NameType;

  @Event() todoCompleted: EventEmitter<Todo>;

  render() {
    return <div>Hello, World! I'm {this.first}</div>;
  }
}

The following data will now be included automatically in components.d.ts:

  import { HTMLRindoElement, JSXBase } from "@rindo/core/internal";
  import { NameType, Todo } from "./components/my-component/my-component";
+ export { NameType, Todo } from "./components/my-component/my-component";
  export namespace Components {
      interface MyComponent {
        "first": NameType;
      }
  }
  export interface MyComponentCustomEvent<T> extends CustomEvent<T> {
      detail: T;
      target: HTMLMyComponentElement;
  }
  declare global {
      interface HTMLMyComponentElement extends Components.MyComponent, HTMLRindoElement {
  }

This allows those types to be easily accessed from the root of the type distribution:

import { NameType, Todo } from '@my-lib/types';

When using dist-custom-elements, these types can now be accessed from the custom element output:

import { NameType, Todo } from '@my-custom-elements-output';

This may clash with any manually created types in existing Rindo projects. Projects that manually create type definitions from components.d.ts will either need to:

• remove the manually created type (if the types generated in components.d.ts suffice)
• update their type creation logic to account for potential naming collisions with the newly generated types

Composition Event Handlers Renamed

The names of Rindo's composition event handlers have been changed in order to correct a casing issue which prevented handlers from being called when events fired. The changes are as follows:

previous name	new name
onCompositionEnd	onCompositionend
onCompositionEndCapture	onCompositionendCapture
onCompositionStart	onCompositionstart
onCompositionStartCapture	onCompositionstartCapture
onCompositionUpdate	onCompositionupdate
onCompositionUpdateCapture	onCompositionupdateCapture

Output Targets

dist-custom-elements Output Target

Add customElementsExportBehavior to Control Export Behavior

customElementsExportBehavior is a new configuration option for the output target. It allows users to configure the export behavior of components that are compiled using the output target. By default, this output target will behave exactly as it did in Rindo v2.0.0.

This config option provides additional behaviors that will alter the default component export OR custom element definition behaviors for this target. The desired behavior can be set via the following in a project's Rindo config:

// rindo.config.ts
import { Config } from '@rindo/core';
export const config: Config = {
  outputTargets: [
    {
      type: 'dist-custom-elements',
      customElementsExportBehavior: 'default' | 'auto-define-custom-elements' | 'bundle' | 'single-export-module',
    },
    // ...
  ],
  // ...
};

Option	Description
default	No additional re-export or auto-definition behavior will be performed. This value will be used if no explicit value is set in the config, or if a given value is not a valid option.
auto-define-custom-elements	A component and its children will be automatically defined with the CustomElementRegistry when the component's module is imported.
bundle	A utility defineCustomElements() function is exported from the index.js file of the output directory. This function can be used to quickly define all Rindo components in a project on the custom elements registry.
single-export-module	All component and custom element definition helper functions will be exported from the index.js file in the output directory (see Defining Exported Custom Elements for more information on this file's purpose). This file can be used as the root module when distributing your component library, see below for more details.

note

This option also has an impact when using the Rindo framework integration output targets. Please see the framework integration migration section below for more information.

Move autoDefineCustomElements Configuration

autoDefineCustomElements was a configuration option to define a component and its children automatically with the CustomElementRegistry when the component's module is imported. This behavior has been merged into the customElementsExportBehavior configuration field. To continue to use this behavior, replace autoDefineCustomElements in your project's rindo.config.ts with the following:

// rindo.config.ts
import { Config } from '@rindo/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'dist-custom-elements',
-      autoDefineCustomElements: true,
+      customElementsExportBehavior: 'auto-define-custom-elements',
      // ...
    },
    // ...
  ],
  // ...
};

Remove inlineDynamicImports Configuration

The inlineDynamicImports configuration option on dist-custom-elements has been removed. Previously, this option would throw an error at build time during the Rollup bundling process if the build contained multiple "inputs" (components).

dist-custom-elements-bundle Output Target

The dist-custom-elements-bundle has been removed starting with Rindo v3.0.0. Users of this output target should migrate to the dist-custom-elements output target.

By default, dist-custom-elements does not automatically define all a project's component's with the CustomElementsRegistry. This allows for better tree-shaking and smaller bundle sizes.

For teams that need to migrate quickly to dist-custom-elements, the following configuration should be close to a drop-in replacement for dist-custom-elements-bundle:

// rindo.config.ts
import { Config } from '@rindo/core';

export const config: Config = {
  outputTargets: [
-    {
-      type: 'dist-custom-elements-bundle',
-      // additional configuration
-    },
+    {
+      type: 'dist-custom-elements',
+      customElementsExportBehavior: 'bundle'
+    },
    // ...
  ],
  // ...
};

However, it does not necessarily improve tree-shaking/bundle size. For more information on configuring this output target, please see the dist-custom-elements documentation

Framework Integration Output Targets

Using includeImportCustomElements

The addition of the customElementsExportBehavior option on dist-custom-elements can also have an impact on the Rindo framework integration output targets if they are configured to use the output from dist-custom-elements (i.e. by setting includeImportCustomElements: true). If you encounter problems with the generated import statements in the component proxy files, setting customElementsExportBehavior: 'single-export-module' in the dist-custom-elements output target config should result in the same behavior as in Rindo V2.

Rindo APIs

Rindo exposes Node APIs for programmatically invoking the compiler. Most users do not use these APIs directly. Unless your project calls these APIs, no action is required for this section.

Flag Parsing, parseFlags()

Rindo exposes an API for parsing flags that it receives from the command line. Previously, it accepted an optional CompilerSystem argument that was never properly used. The flag has been removed as of Rindo v3.0.0. To migrate, remove the argument from any calls to parseFlags imported from the Rindo CLI package.

import { parseFlags } from '@rindo/core/cli';
- parseFlags(flags, compilerSystem);
+ parseFlags(flags);

Destroy Callback, addDestroy(), removeDestroy()

The Rindo CompilerSystem interface has a pair of methods, addDestroy and removeDestroy that were previously misspelled. If your codebase explicitly calls these methods, they need to be updated. Replace all instances of addDestory with addDestroy and all instances of removeDestory with removeDestroy The functionality of these methods remains the same.

End-to-End Testing

Puppeteer v10+ Required

Versions of Puppeteer prior to Puppeteer version 10 are no longer supported. In newer versions of Puppeteer, the library provides its own types, making @types/puppeteer no longer necessary. Ensure that Puppeteer v10 or higher is installed, and that its typings are not:

npm

$ npm install puppeteer
$ npm uninstall @types/puppeteer

Yarn

$ yarn add puppeteer
$ yarn remove @types/puppeteer

pnpm

$ pnpm add puppeteer
$ pnpm remove @types/puppeteer

Additional Packages

In order to guarantee that other @rindo/ packages will continue to function as expected, it's recommended that a project that uses any of the packages listed below updates to the listed minimum package version.

Package	Minimum Package Version	GitHub	Documentation
@rindo/sass	2.0.1	GitHub	GitHub README
@rindo/store	2.0.1	GitHub	Rindo Doc Site
@rindo/react-output-target	0.5.0	GitHub	Rindo Doc Site
@rindo/kdu-output-target	0.8.0	GitHub	Rindo Doc Site