DOCSEARCHbyAlgolia
Submit Docs

Aurelia CLI

repository·master·Indexed 19 days ago

https://github.com/aurelia/cli

Command-line tooling for the Aurelia platform (version 3.0.8). The CLI provides tools to scaffold new projects via the `new` command, manage application configuration through `aurelia.json` using the `config` command, and scaffold code with the `generate` command. It supports running Gulp tasks with dependency injection and allows for programmatic access to the CLI, Project, and UI classes. Requires Node.js version 10.12.0 or above.

Tokens
4.1K
Snippets
18
Records
23
Agent score
62%

What's inside aurelia-cli

  1. Build and link the Aurelia CLI locally

    master

    If you are developing the CLI itself and want to test your changes against a real Aurelia project, follow these steps to build and link it:

    1. Clone the repository: git clone https://github.com/aurelia/cli.git
    2. Enter the directory: cd cli
    3. Install dependencies: npm install
    4. Create a global link: npm link
    5. Create a new project using the linked CLI: au new (or use an existing project).
    6. Link the CLI to your specific project: In your project directory, run npm link aurelia-cli. This ensures that commands like au run use your local development version of the CLI.
    git clone https://github.com/aurelia/cli.git
cd cli
npm install
npm link
# In your project directory:
npm link aurelia-cli

  2. Create a new Aurelia project

    master

    You can create a new Aurelia project using the au new command. This command is a wrapper around npx makes aurelia/v1. You can also use the makes command directly to scaffold a new project.

    To create a project using the CLI wrapper:

    au new

    To create a project directly using makes:

    npx makes aurelia/v1

  3. Inject Aurelia dependencies into Gulp tasks

    master

    The Aurelia CLI extends gulp.series and gulp.parallel to support injectable tasks. If a task function has an inject method (or is defined in a way that the CLI recognizes as injectable), the CLI will automatically resolve the task from the Aurelia Container before execution.

    To make a task injectable, ensure it is structured to be compatible with the Aurelia dependency injection system, and the CLI will handle the container.get(task) resolution and binding the execute method automatically.

    // Conceptual representation of an injectable task used by the CLI
class MyTask {
  static inject() {
    return [/* dependencies */];
  }

  execute() {
    // Task logic here
  }
}

// The CLI will wrap this so that gulp.series(MyTask) works

  4. Manage Aurelia project configuration via aurelia.json

    master

    The Aurelia CLI manages project settings through an aurelia.json file located in the aurelia_project/ directory of your project. You can interact with this configuration using CLI commands (implied by the Configuration class logic) to get, set, add, remove, or clear specific configuration keys using dot notation.

    Key Operations

    • Get: Retrieve the value of a configuration key.
    • Set: Assign a value to a specific key. If the path doesn't exist, it may fail depending on the parent structure.
    • Add: Add a value to a key. If the target is an array, it appends the value. If the target is an object, it performs an Object.assign merge.
    • Remove: Remove a property from an object or an element from an array using index notation.
    • Clear: Delete a specific property from an object.

    Key Syntax

    Use dot notation to traverse the configuration object. For array elements, use bracket notation with the index:

    • path.to.key for object properties.
    • path.to.array[0] for the first element in an array.

  5. How the Aurelia CLI command resolution works

    master

    The Aurelia CLI resolves commands using a specific hierarchy:

    1. Built-in/Aliased Commands: The CLI first checks for a command module matching the input (or an alias defined in commands/alias.json).
    2. Project Tasks: If no built-in command is found, the CLI attempts to resolve the input as a task within your Aurelia project using project.resolveTask(). If a task is found, it executes the gulp command module with the resolved taskPath.
    3. Help Command: If the command is invalid or no command text is provided, the CLI defaults to the help command.

    Commands can be namespaced using a colon (:), for example: module:name. If the name is omitted, it defaults to default.

  6. Run the Aurelia CLI

    master

    The aurelia-cli is a command-line interface used to manage Aurelia projects. It can be run globally or locally within a project.

    • Global Execution: If you run aurelia new, the CLI uses its own internal logic to scaffold a new project.
    • Local Execution: For other commands (like build or serve), the CLI attempts to resolve and use the aurelia-cli package installed locally within your project's node_modules. This ensures that the CLI version matches your project's requirements.

    Requirements:

    • Node.js version 10.12.0 or above is required.
    # Example of running the CLI (assuming it is installed globally or via npx)
aurelia new my-app

  7. Programmatic access to Aurelia CLI

    master

    The aurelia-cli package exports several classes and modules for interacting with Aurelia projects programmatically. This allows you to automate CLI tasks like building, running, or managing projects within your own tools or scripts.

    Key exports include:

    • CLI: The main entry point for executing CLI commands.
    • Project: Represents an Aurelia project.
    • ProjectItem: Represents an item within a project.
    • CLIOptions: Configuration options for the CLI.
    • UI: Interface for user interaction.
    • Configuration: Handles project configuration.
    • build: Module for build-related operations.
    • NPM and Yarn: Package manager abstractions.
    • reportWebpackReadiness: Utility to report Webpack readiness.
    const { CLI, Project, build } = require('aurelia-cli');

// Example of how you might access these components
// Note: Actual implementation usage depends on the specific class methods
const cli = new CLI();
const project = new Project();

  8. Reference: Configuration management actions

    master

    The following actions are supported for manipulating the aurelia.json configuration file:

    ActionDescription
    getReturns the current value of the specified key.
    setSets the value of the specified key.
    addAdds a value to an existing key. Appends to arrays or merges into objects.
    removeRemoves an item from an array (via index) or a property from an object.
    clearDeletes a property from an object.

    Note: When using add, if you provide an object to an existing object key, it performs a shallow merge using Object.assign.

  10. Reference: 'config' command flags and parameters

    master

    The config command uses the following parameters and flags to manipulate configuration settings.

    Parameters:
  key (optional): The key you want to get or set. Supports hierarchies and array indexes (e.g., build.targets[0], arrayWithArray[2].[1]).
  value (optional): The value you want to set the key to. Supports JSON (e.g., "{ \"myKey\": \"myValue\" }").

Flags:
  --get: Gets the content of key, ignoring value parameter.
  --set: Sets the content of key to value, replacing any existing content.
  --clear: Deletes the key and all its content from the configuration.
  --add: If value or existing content of the key is an array, adds value(s) to existing content. If value is an object, merges it into existing content of key.
  --remove: If value or existing content of the key is an array, removes value(s) from existing content. If value or existing content of the key is an object, removes key(s) from existing content of key.
  --no-save: Don't save the changes in the configuration file.
  --no-backup: Don't create a backup configuration file before saving changes.

  11. Use 'new' command flags and options

    master

    The new command supports several flags to customize the project scaffolding process:

    • --here: Instead of creating a new directory for the project, the project is initialized directly in the current working directory.
    • --plugin: Scaffolds the project as an Aurelia plugin instead of a standard application.
    • --select <features>: Preselects specific features (e.g., --select cli-bundler,alameda,karma) and enables unattended mode, bypassing the interactive wizard.
    aurelia new <project-name> --here
aurelia new <project-name> --plugin
aurelia new <project-name> --select cli-bundler,alameda

  12. Create a new Aurelia application with 'new'

    master

    Use the new command to scaffold a new Aurelia application project. This command wraps npx makes aurelia/v1. You can optionally provide a project name as a parameter, or run the command without one to enter an interactive wizard that will prompt you for the project name and other configurations.

    aurelia new <project-name>