Getting Started

dreamland is ESM-only and imports itself using node-style imports (ie dreamland/router imports dreamland/core to use the JSX factory). This means you'll either need a bundler or an importmap to use it. Additionally, dreamland exposes one global (the use function) with Object.defineProperty so it doesn't play nice with multiple versions in the dependency tree. Sadly use can't be exported via ESM as the state system requires it to actually be a getter that returns a function.

dreamland targets the oldest browsers that support :where() (which is needed for dreamland's scoped CSS - similar to how Svelte needs it), which are Chrome 88, Firefox 78, and Safari 14. Transpilers can be used to run dreamland core on older versions, but scoped CSS will break.

Pure JS

An importmap is required as dreamland imports itself internally. Here's an example importmap, assuming the dreamland package is in dist:

<script type="importmap">
	{
		"imports": {
			"dreamland/core": "./dist/core.js",
			"dreamland/js-runtime": "./dist/js-runtime.js",
			"dreamland/router": "./dist/router.js"
		}
	}
</script>

Then you can use dreamland like normal JS with a bundler:

<script type="module">
	import { css } from "dreamland/core";
	import { html } from "dreamland/js-runtime";

	let App = function () {
		this.counter = 0;

		return html`
			<div>
				<h1>:3</h1>
				<button on:click=${() => this.counter++}>
					Count: ${use(this.counter)}
				</button>
			</div>
		`;
	};
	App.style = css`
		:scope {
			border: 4px dashed cornflowerblue;
			padding: 1em;
		}
	`;

	document.querySelector("#app").replaceWith(html`<${App} />`);
</script>

TypeScript

Install dreamland (pnpm i dreamland) then add this to your tsconfig:

{
	"compilerOptions": {
		"jsx": "react-jsx",
		"jsxImportSource": "dreamland"
	}
}

You can also use the old JSX transform (the h(el, props, ...children) one) by adding this to your tsconfig instead:

{
	"compilerOptions": {
		"jsx": "react",
		"jsxFactory": "h",
		"jsxFragmentFactory": "Fragment"
	}
}

Note that you'll need to manually import h and Fragment from dreamland/core if you use this method.

JS with bundlers (Vite, esbuild, etc)

If you're using vite, just add jsxPlugin from dreamland/vite to your vite config:

import { jsxPlugin } from "dreamland/vite";
import { defineConfig } from "vite";

export default defineConfig({
	plugins: [jsxPlugin()],
});

This just sets the following vite esbuild config:

{
	esbuild: {
		jsx: "automatic",
		jsxImportSource: "dreamland"
	}
}

dreamland provides a tagged template function for writing HTML in the dreamland/js-runtime export.