Installation

We’ll always need: angular-three core package and the three itself.

Using template repository

The easiest way to get started with Angular Three is to use the template repository

The template repository is kept up to date with the latest version of Angular Three.

Did you know?

If you have the Github CLI installed, you can use the gh repo create command to clone the template repository directly from the command line.

gh repo create <username>/<repository-name>
  --template angular-threejs/template
  --public
  --clone

Angular CLI / Nx CLI

1. Install angular-three-plugin as a dev dependency

npm

npm install --save-dev angular-three-plugin

yarn

yarn add --save-dev angular-three-plugin

pnpm

pnpm add --dev angular-three-plugin

2. Use a schematic / generator to set up angular-three

ng

ng generate angular-three-plugin:init

nx

nx generate angular-three-plugin:init

Code editor setup

Jetbrains IDE

angular-three comes with a web-types.json that allows Jetbrains IDEs to recognize elements from angular-three. You don’t have to do anything to get this setup.

VS Code

angular-three comes with a metadata.json that you can use to setup html.customData to allow VS Code to recognize angular-three elements.

.vscode/settings.json

{
  "html.customData": ["node_modules/angular-three/metadata.json"]
}

Note

angular-three-plugin:init should set this up for you.

Neovim

Neovim can set up metadata.json via html lsp with the following options:

• init_options.dataPaths
• handlers['html/customDataContent']

Specific setup depends on your neovim configuration. Here’s an example of LazyVim

lua/plugins/lsp.lua

return {
  "neovim/nvim-lspconfig",
  opts = {
    setup = {
      html = function(_, opts)
        local util = require("lspconfig.util")
        local root_dir = util.root_pattern("package.json", "node_modules")(vim.fn.getcwd())

        if root_dir then
          local metadata_path = vim.fs.normalize(root_dir .. "/node_modules/angular-three/metadata.json")

          if vim.fn.filereadable(metadata_path) == 1 then
            opts.init_options = vim.tbl_deep_extend("force", opts.init_options or {}, {
              dataPaths = opts.init_options and opts.init_options.dataPaths or {},
            })

            table.insert(opts.init_options.dataPaths, metadata_path)

            opts.handlers = vim.tbl_deep_extend("force", opts.handlers or {}, {
              ["html/customDataContent"] = function(_, result)
                local function exists(name)
                  return type(name) == "string" and vim.loop.fs_stat(name) ~= nil
                end

                if result and result[1] and exists(result[1]) then
                  local ok, content = pcall(vim.fn.readfile, result[1])
                  return ok and table.concat(content, "\n") or ""
                end
                return ""
              end,
            })
          end
        end

        return false
      end,
    },
  },
}

Auxiliary packages

Once you have angular-three-plugin installed, you can invoke the angular-three-plugin:aux generator to add the auxiliary packages.

npx ng g angular-three-plugin:aux

Compatibility Matrix

Versioning Semantics

Angular Three follows a modified semantic versioning scheme to balance stability with the fast-paced Three.js ecosystem:

Version	Meaning	Examples
Patch (x.x.X)	Bug fixes and new features. No breaking changes ever.	4.0.0 → 4.0.1
Minor (x.X.0)	Breaking changes for Three.js version bumps, or Angular minor updates that require breaking changes.	4.0.x → 4.1.0
Major (X.0.0)	True breaking changes: API changes, Angular major bumps, or other peer dependency major bumps.	4.x.x → 5.0.0

Why this approach?

Three.js releases frequently, and following true semver would exhaust major version numbers quickly. By using minor versions for Three.js breaking changes, we maintain a practical versioning scheme while clearly communicating compatibility boundaries.

Core Compatibility

Angular Three	Three.js	Angular	ngxtension