Triangular - The CLI tool for Angular projects

Documentation

Get started with Triangular, learn the fundamentals and explore advanced topics.

• [Getting started][quickstart]
• [CLI][cli]
• [Workspace and project file structure][filestructure]
• [Workspace configuration][workspaceconfig]
• [Schematics][schematics]

Development Setup

Prerequisites

• Install [Node.js] which includes [Node Package Manager][npm]

Setting Up a Project

Install Triangular globally:

npm install -g triangular

Create workspace:

Run the application:

cd [PROJECT NAME]
tri serve

Testing Local Changes

If you are contributing to this repository and want to test your changes, you can build the CLI locally and install it in your project.

To make a local build:

This generates tarballs in the dist/ directory. To use these locally built tools in another repository, install the generated packages:

cd path/to/example-project
npm install -D path/to/triangular/dist/*.tgz

When using the CLI in that project, it will automatically use the local build.

Using the 'tri' command

When you install Triangular globally, you can use the tri command.

Verifying against Official Tools

To verify your local changes, you can compare the output of a build using your local CLI with one using the official version.

1. Create a baseline build: In your example project, ensure you are using the official version (e.g., from npm) and run a build:

   # Using official package
   npm install @angular/cli@latest
   npm run build
   mv dist dist-official

2. Create a comparison build: Install your local build tarballs as described above and run the build again:

   # Using local built @angular/cli
   npm install -D path/to/angular-cli/dist/*.tgz
   npm run build
   mv dist dist-local

3. Compare the results: You can now compare the two directories to see the differences in the generated bundles:

   diff -r dist-official dist-local

   Note: Some differences are expected due to timestamps, randomly generated hashes, or minor version differences in dependencies. Focus on the actual JavaScript content changes.

Benchmarking tri vs Others

To benchmark the performance improvements of tri (OXC-based) against official tools, you can follow these steps.

1. Prepare your environment

Ensure you have a project to test with. For consistent results, it is recommended to run benchmarks on a "cold" build (after removing dist and .angular folders).

2. Simple Benchmarking using time

You can use the built-in time command to get basic timing information.

Baseline (Official):

# Ensure official CLI is installed
npm install @angular/cli@latest
rm -rf dist .angular
time npx ng build

Comparison (Tri):

# Ensure local triangular builds are installed
npm install -D path/to/triangular/dist/*.tgz
rm -rf dist .angular
time npx ng build

3. Advanced Benchmarking using hyperfine

For more accurate and statistically significant results, we recommend using hyperfine.

First, create two separate directories or use a way to switch between versions easily. A good approach is to have two identical projects: project-official and project-triangular.

hyperfine --prepare 'rm -rf dist .angular' \
  --name "Official CLI" "cd project-official && npx ng build" \
  --name "Triangular (OXC)" "cd project-triangular && npx ng build"

4. Interpreting Results

tri focuses on speeding up the transpilation phase of the build. In large projects with many TypeScript files, you should see a noticeable decrease in the "Building..." phase of the CLI output.

Triangular is a cross-platform, fast, scalable SDK powered by a Rust-based compiler toolchain (OXC). It is designed to be a high-performance alternative to traditional tools.