Skip to content
Alloy

Getting started

Quick Start

Initialize a new project with npm init:

Terminal window
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

Terminal window
npm init

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

Install TypeScript

Terminal window
npm install -d typescript

Install alloy

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

Terminal window
npm 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.

Terminal window
npm 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:

Terminal window
npx alloy build

And test with:

Terminal window
vitest run