quaaant-cli

Quaaant CLI documentation

Overview

The Quaaant NPM package offers a command-line interface (CLI) that enables developers to seamlessly integrate and manage digital design assets from the Quaaant platform into their JavaScript projects.

This tool provides a powerful and flexible way to integrate Quaaant design assets into your development workflows, ensuring assets are up-to-date and correctly configured according to your project specifications.

Key features

• Direct access to design assets: Pull assets directly into your projects from designs created in Adobe Illustrator, Photoshop, or Figma using the Quaaant platform. This integration ensures a smooth workflow from design to development.

• Custom configuration: Fine-tune how assets are incorporated into your project with extensive configuration options.

• Simple update process: Update your assets easily with a simple command. This command can be integrated into your automatic build process, allowing updates to be seamlessly incorporated into your workflow whenever you deploy or build your project.

Installation

To install the Quaaant CLI globally, use the following command:

npm install -g quaaant-cli

After installation, you can use the quaaant init command to generate a .env file and an example quaaant-config.json file in your project’s root directory.

quaaant init

Setup instructions

Environment configuration

After running quaaant init, visit the Quaaant app at https://app.quaaant.com/dev-tokens. Create your development token by selecting the projects it should be associated with. This token authenticates your requests to the Quaaant API.

Open the .env file in your project’s root directory and replace "your_development_token_here" with your development token:

QUAAANT_DEV_TOKEN="your_development_token_here"

Configuration file

The quaaant init command also creates a quaaant-config.json file in your project’s root directory. This configuration file specifies the rules and parameters for asset integration, ensuring that they are managed according to your specific project requirements.

You can modify this file to define asset handling for each project.

Example Configuration:

{
    "quaaantConfigVersion": 1,
    "projects": [
        {
            "uuid": "example-project-uuid",
            "branch": "feature/new-ui",
            "path": "assets/ui-elements",
            "subfolders": true,
            "subfolderSeparator": "_",
            "clearBeforePull": true,
            "prefix": "quaaant-",
            "suffix": "-v1.2",
            "options": {
                "omitColors": true
            }
        },
        {
            "uuid": "another-project-uuid",
            "path": "assets",
            "assets": [
                "asset1-name",
                "asset2-name"
            ]
        }
    ]
}

This configuration file allows for detailed control over asset management, from directory structure and file naming conventions to selective asset integration.

Configuration options

This section provides a detailed explanation of the key configuration options available in the quaaant-config.json file. Each option is designed to optimize how assets are managed and integrated into your projects.

Option	Description	Mandatory	Default
uuid	Unique identifier for the Quaaant project	Yes	None
branch	Specifies the branch of the project assets to be pulled	No	main
path	The local directory path where the assets will be saved, relative to the project root	No	Project root
assets	An array of asset names that you want to pull from the project	No	All assets
subfolders	Determines whether to organize downloaded assets into subfolders	No	false
subfolderSeparator	The character used to separate different sections of the asset name	No	_
clearBeforePull	Determines whether to delete the existing contents of the specified path	No	false
prefix	String to prepend to the names of downloaded assets	No	None
suffix	String to append to the names of downloaded assets	No	None
options	A set of additional settings that can be configured per project	No	None

uuid

The uuid property is a unique identifier for the Quaaant project from which assets are to be pulled.

Example

"uuid": "example-project-uuid"

To locate the UUID required for your configuration, navigate to the “Dev Tokens” page on the Quaaant app by following this link: https://app.quaaant.com/dev-tokens. Once there, select the specific token relevant to your project.

A modal window will appear displaying a list of associated projects for that token. Next to each project name, there is a ‘Copy’ button which allows you to easily copy the UUID for the project you wish to configure. This UUID is essential for linking your project configuration to the correct assets on the Quaaant platform.

branch

Specifies the branch of the project assets to be pulled. This can be useful for managing different versions, stages of asset development, or for experimenting with new designs.

Examples

Specific feature branch:

"branch": "feature/new-ui"

Release branch:

"branch": "release/2023-q1"

If not specified, assets will be pulled from the main branch.

path

The local directory path where the assets will be saved. The path should be relative to the project’s root.

Examples

Specific directory:

"path": "assets/ui-elements"

Generic directory:

"path": "assets"

If no path is specified, assets will be saved directly in the project’s root directory.

assets

An array of asset names that you want to pull from the project. If this option is specified, only the assets with the names in this array will be pulled. If this option is not specified, all assets from the project will be pulled.

Example

"assets": [
    "asset1-name",
    "asset2-name"
]

subfolders

Determines whether to organize downloaded assets into subfolders based on their names. If a separator is detected in the asset name, it will be used as a path separator for creating the asset’s path.

For example, if the asset name is icons_home.svg and the subfolderSeparator is set to _, then the asset will be saved as /icons/home.svg.

Example

Subfolders from asset name:

{
    "subfolders": true,
    "subfolderSeparator": "_"
}

subfolderSeparator

The character used to separate different sections of the asset name, which dictates how subfolders are named. Only relevant if subfolders is true.

Examples

Underscore separator:

"subfolderSeparator": "_"

Dash separator:

"subfolderSeparator": "-"

clearBeforePull

Determines whether to delete the existing contents of the specified path before downloading new assets. Please note that if an asset with the same name is pulled, it will overwrite the existing asset regardless of this setting.

Example

Clear folder before pulling new assets:

"clearBeforePull": true

prefix

The prefix option allow you to prepend a string to the names of downloaded assets, which can help in organizing or versioning files.

Examples

Branding:

"prefix": "quaaant-"

Departmental categorization:

"prefix": "marketing-"

Adding a prefix helps in identifying and sorting assets more efficiently within your project structure.

suffix

The suffix option allows you to append a string to the names of downloaded assets. This can be particularly helpful for versioning files or specifying certain attributes that help in asset management.

Examples

Versioning:

"suffix": "-v1.2"

Localization:

"suffix": "-en"

Project phase:

"suffix": "-beta"

options

A set of additional settings that can be configured per project, such as omitting color information from the downloaded assets.

Example

"options": {
    "omitColors": true
}

Usage

To initiate the synchronization of assets with your project, run the following command from the root directory of your project:

quaaant sync

This command activates the asset pull process as outlined in your quaaant-config.json file. It intelligently manages the download and organization of various asset types according to the configurations you’ve specified.