Getting started

Quick Start

Initialize a new project with npm init:

mkdir my-project
cd my-project
npm init @alloy-js
pnpm install
pnpm build

The following sections show what you need to add alloy to an existing project, or may be useful if you’d like to customize your setup.

Initialize a new npm package

npm

npm init

pnpm

pnpm init

Ensure your package.json file has "type": "module".

Install TypeScript

npm

npm install -d typescript

pnpm

pnpm install -D typescript

Install alloy

You will need @alloy-js/core as well as the packages for any languages you will want to generate.

npm

npm install @alloy-js/core @alloy-js/cli @alloy-js/typescript

pnpm

pnpm install @alloy-js/core @alloy-js/cli @alloy-js/typescript

Install test dependencies

While you can use any test framework, vitest is recommended. The following assumes you are using vitest.

npm

npm install -d vitest @alloy-js/rollup-plugin

pnpm

pnpm install -D vitest @alloy-js/rollup-plugin

Next, create your vitest.config.js:

vitest.config.js

import { defineConfig } from "vitest/config";
import alloyPlugin from "@alloy-js/rollup-plugin";

export default defineConfig({
  test: {
    include: ["test/**/*.test.ts", "test/**/*.test.tsx"],
    exclude: ["test/**/*.d.ts"]
  },
  esbuild: {
    jsx: "preserve",
    sourcemap: "both"
  },
  plugins: [
    alloyPlugin(),
  ],
});

The esbuild jsx preserve option is important, don’t forget it. Otherwise, esbuild will munge whitespace within JSX before alloy has a chance to process it.

Building and testing

You can build your project with the following command:

npx alloy build

And test with:

vitest run