Getting Up & Running with GitHub Catalyst
Tags: webcomponents
Published: 2021-02-18 15:22:28

---
title: Getting Up & Running with GitHub Catalyst
published: true
description: A super quick quickstart guide for GitHub Catalyst
tags: webcomponents
---

[GitHub Catalyst](https://github.github.io/catalyst/) is a library that makes it easier to develop [Web Components](https://developer.mozilla.org/en-US/docs/Web/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](https://github.com/github/catalyst/issues/116).

## 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:

```shell
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:

```json
{
	"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:

```javascript
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:

```typescript
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
<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!

![image](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/e9ee7vcy52lxixgda7u5.png)

Now you're up and running, you can head back to the [Catalyst guide](https://github.github.io/catalyst/guide/introduction/) for a proper deep dive.