Getting Up & Running with GitHub Catalyst

Sam Strong — Thu, 18 Feb 2021 15:22:28 +0000

GitHub Catalyst is a library that makes it easier to develop Web Components.

Here's a short guide to getting up and running with Catalyst.

Disclaimer: This is not a guide for learning how to use Catalyst. The sole purpose of this guide is to get a Catalyst example up and running.

Disclaimer 2: This is the simplest possible set up I could come up with and doesn't include any loveliness like hot reloading.

Disclaimer 3: I find the various front end configuration bits and pieces quite baffling at times and one of the Catalyst folks helped me out.

Tooling

You'll be using NPM to install stuff, so make sure you have Node installed.

Start with an empty folder and run these commands in your console:

npm init -y
npm install webpack webpack-cli typescript ts-loader --save-dev
npm install @github/catalyst --save

These will initialise your project with enough defaults to use Node packages. Then we install Webpack (and its CLI) as well as TypeScript and the TypeScript loader for Webpack (Catalyst components are written in TypeScript).

The last line installs Catalyst itself.

Configuration

Next we need to set up our Webpack and TypeScript configurations.

Create a tsconfig.json file in the root of your project and paste in the following:

{
    "compilerOptions": {
        "moduleResolution": "node",
        "outDir": "./dist/",
        "noImplicitAny": true,
        "module": "es2020",
        "target": "es2020",
        "allowJs": true,
        "experimentalDecorators": true
    }
}

Create a webpack.config.js file in the root of your project and paste in the following:

const path = require('path');

module.exports = {
    mode: 'development',
    devtool: 'inline-source-map',
    entry: './src/index.ts',
    module: {
        rules: [
            {
                test: /\.m?js/, resolve: {
                    fullySpecified: false
                }
            },
            {
                test: /\.tsx?$/,
                use: 'ts-loader',
                exclude: /node_modules/,
            },
        ],
    },
    resolve: {
        extensions: ['.tsx', '.ts', '.js'],
    },
    output: {
        filename: 'bundle.js',
        path: path.resolve(__dirname, 'dist'),
    },
};

The Code

Now our tooling is in place, we can write some code! Create two folders in the root of your project, one called src and the other called dist.

In the src folder create a file called index.ts and paste in the following code:

import { controller, target } from "@github/catalyst"

@controller
class HelloWorldElement extends HTMLElement {
  @target name: HTMLInputElement;
  @target output: HTMLElement;

  greet() {
    this.output.textContent = `Hello, ${this.name.value}!`;
  }
}

In the dist folder create a file called index.html and paste in the following markup.

<html>

<body>
    <script src="bundle.js"></script>
    <hello-world>
        <input data-target="hello-world.name" type="text">

        <button data-action="click:hello-world#greet">
          Greet
        </button>

        <span data-target="hello-world.output">
        </span>
      </hello-world>
</body>

</html>

The Result

Go back to your console and run webpack. This will generate the JavaScript bundle that your project needs to work.

Open the index.html file in a browser. Type something into the text box and click "Greet". Huzzah, your Catalyst component has done a thing!

Now you're up and running, you can head back to the Catalyst guide for a proper deep dive.

DEV Community: Sam Strong

Getting Up & Running with GitHub Catalyst

Tooling

Configuration

The Code

The Result