This guide will walk you through getting started with Palette. First, we'll make a tiny HTML file with our first ever Palette Component using the hosted Palette CDN, then we'll set up a scaffolded project using Bun to install the library locally.
In the Browser
Palette is available for use via the Palette CDN. To include Palette on any webpage, just import it inside a script module:
<!-- Development Bundle, has clear errors, dev warnings, but is larger -->
<script type="module">
import { define } from "https://cdn.palette.surf/pkg/palette/latest/palette.dev.js"
</script>
<!-- Production Bundle, much smaller with no warnings and terse errors -->
<script type="module">
import { define } from "https://cdn.palette.surf/pkg/palette/latest/palette.js"
</script>
Since Palette does not require a build step, it works right in the browser with standard JavaScript.
Create a Webpage
Make an HTML file somewhere on your computer. Your choice, you don't need to tell me
where you put it, I won't remember anyway. You can call it demo.html.
Open it up in your favorite code editor and copy in this HTML:
<!doctype html>
<html lang="en-US">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width" />
<!-- Define our component right here because we can! -->
<script type="module">
import { define, html, css } from "https://cdn.palette.surf/pkg/palette/latest/palette.dev.js";
define("hello-world", {
template: html`<p>Hello, world!</p>`,
style: css`
:host {
--color: red;
}
p {
color: var(--color);
font-size: 3rem;
font-style: italic;
text-align: center;
}
`,
script() {
setInterval(() => {
const rgb = [
Math.floor(Math.random() * 255),
Math.floor(Math.random() * 255),
Math.floor(Math.random() * 255),
];
this.style.setProperty("--color", `rgb(${rgb.join(",")})`)
}, 1000);
}
});
</script>
<title>My First Palette Component</title>
</head>
<body>
<hello-world></hello-world>
</body>
</html>
If you now open up that HTML file, you'll see a VERY fancy "Hello, world!"
Here's whats happening:
define("hello-world", {
We're using the define() helper to streamline creating a Palette
Component. We're making a Component which will render under the HTML tag,
<hello-world>.
{
template: html`<p>Hello, world!</p>`,
style: css`
:host {
--color: red;
}
p {
color: var(--color);
font-size: 3rem;
font-style: italic;
text-align: center;
}
`,
}
These two properties define the HTML and CSS associated with this Component. The
html helper creates a standard HTML <template> element, and the css helper
returns a CSSStyleSheet array. The stylesheet is then adopted to the Component's
ShadowRoot.
script() {
setInterval(() => {
const rgb = [
Math.floor(Math.random() * 255),
Math.floor(Math.random() * 255),
Math.floor(Math.random() * 255),
];
this.style.setProperty("--color", `rgb(${rgb.join(",")})`)
}, 1000);
}
This is the primary scripting setup for the component. script() runs when the
Component mounts to the page. You can optionally return a function from script()
to handle cleaning up resources when the component unmounts, or use another
Lifecycle Method.
Congratulations: you've officially used Palette. How about something slightly more involved?
With a Bundler
In this section, we'll quickly create a small project using Bun as the package manager and bundler. This way, we can install the library with it's TypeScript definitions and other utilities for a better developer experience.
First Things First
We're going to need a project. Make a directory called hello-palette and
initialize a project. We will also need an index.html file, so make that too.
mkdir hello-palette
cd hello-palette
bun init -y .
touch index.html
Our directory should now more or less look like:
+ Project Root
|- index.html
|- index.ts
|- package.json
|- tsconfig.json
|- node_modules/
|- bun.lock
Start by opening up index.html and adding in some basic scaffolding:
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width" />
<title>My Palette Webapp</title>
<!-- We'll import the index.ts file and write our code there -->
<script module src="./index.ts"></script>
</head>
<body>
<!-- This will be our component! -->
<hello-world></hello-world>
</body>
</html>
And now we get to the good part.
Install Palette
Palette is available to install via any NPM-compatible package manager:
bun add @rusticarcade/palette
npm i --save @rusticarcade/palette
yarn add @rusticarcade/palette
Other Installation Options
If you would prefer to install directly from the Palette hosted NPM repository,
you can configure your package manager to use this URL for @rusticarcade scoped
packages:
https://git.astral.camp/api/packages/rusticarcade/npm
For example, to set up Bun to use this repository, set this in your bunfig.toml:
[install.scopes]
"@rusticarcade" = "https://git.astral.camp/api/packages/rusticarcade/npm"Making the Component
Now, open up index.ts and plop in a basic Palette component:
import { define, html, css } from "@rusticarcade/palette";
define("hello-world", {
template: html`<p>Hello, world!</p>`,
style: css`
:host {
--color: red;
}
p {
color: var(--color);
font-size: 2rem;
font-style: italic;
}
`;
script() {
const rgb = [
Math.floor(Math.random() * 255),
Math.floor(Math.random() * 255),
Math.floor(Math.random() * 255),
];
setInterval(() => {
this.style.setProperty("--color", `rgb(${rgb.join(",")})`)
}, 2000);
}
})
And you've done it. You can now enjoy your flashy "Hello World," or read on for more ways to build cool stuff with Palette.