Skip to main content

@tramvai/cli

CLI interface for resolving actual problems and tasks of frontend CI. Reduces complexity of setting up webpack, typescript, babel, postcss and other tools.

@tramvai/cli may build projects to production, run code in development mode with automatic rebuilds, project analyze and code generation

Installation​

Global installation on the developer machine. After that the new command tramvai will be available in terminal.

npm i -g @tramvai/cli

Local installation to the project

npm i --save-dev @tramvai/cli

API​

Commands​

After any command you can pass --help string, e.g. tramvai --help or tramvai start --help. After that you will see description of the command and its options.

  • tramvai new - generate new tramvai app with @tramvai/cli
  • tramvai start - run app in the development mode
  • tramvai start-prod - run app in development mode, but code will be build in the production mode
  • tramvai build - build an app for server and client
  • tramvai static - generate static HTML for application pages
  • tramvai benchmark - run benchmark for application build (run build multiple times and calculate mean values)
  • tramvai generate - code generation for different components. E.g. new projects, react components, actions and etc.
  • tramvai update - update @tramvai/cli and all of the @tramvai and @tramvai-tinkoff dependencies in the project. This command additionally executes dependency deduplication and code migrations
  • tramvai add - add @tramvai or @tramvai-tinkoff dependency to the app. This command additionally executes dependency deduplication and code migrations

Explanation​

Workspaces​

If you are using monorepo, you may not want to install all tramvai modules into your repository root. CLI can automatically define monorepo context and provides some special behaviour and options for ceratin commands:

  • tramvai new will install all tramvai modules (except @tramvai/cli) into provided app workspace if monorepo template chosen
  • tramvai add supports --app or -a parameter. You can provide any app name from your tramvai.json to install module into workspace
  • tramvai update will automatically update tramvai modules for all existing workspaces in your project

Notifications settings​

Inside tramvai.json the settings for the notification can be specified at path notifications. Parameters are passed to webpack-build-notifier. You can specify global configuration or a specific configuration either for client or server build.

{
  "notifications": {
    "suppressSuccess": "always",
    "server": {
      "suppressWarning": true
    },
    "client": {
      "activateTerminalOnError": true
    }
  }
}

CSS class names generation settings​

Name generation is configured via the options cssLocalIdentNameDev and cssLocalIdentNameProd (common option cssLocalIdentName might be used to specify settings for both prod and dev).

{
  "postcss": {
    "cssLocalIdentName": "[hash:base64:5]" // default value (deprecated)
  }
}

or

{
  "postcss": {
    "cssLocalIdentName": {
      "development": "[name]__[local]_[minicss]", // available values see in the docs to [css-loader](https://github.com/webpack-contrib/css-loader)
      "production": "[minicss]" // additionally new tag `minicss` can be used for the generating minimal css names. Based on [article](https://dev.to/denisx/reduce-bundle-size-via-one-letter-css-classname-hash-strategy-10g6)
    }
  }
}

CSS modules processing​

By default, all *.css imports will be processed as CSS Modules.

IF you want to disable Modules for some files, for example with global styles, you can do it by adding cssModulePattern regexp to the config:

{
  "postcss": {
    // CSS Modules processing will be skipped for *.global.css files
    "cssModulePattern": "^(?!.*global\\.css$).*$"
  }
}

Polyfills for the standard NodeJS modules​

By default, webpack starting with 5th version, do not add polyfills to browser bundle when using nodejs standard modules in the browser code, e.g. when using crypto, path, process, buffer, etc.

@tramvai/cli explicitly adds polyfills for path and process modules as these modules are often used and lightweighted.

Checking TypeScript types​

Checking types is enabled by flag checkAsyncTs.

When running tramvai start ts compilation and type checks will be executed.

Inside tramvai.json

"checkAsyncTs": {
  "failOnBuild": true, // optional
  "pluginOptions": {} // optional
},

failOnBuild adds type checks when running tramvai build. This way build will fail in case of wrong types.

pluginOptions – list of the additional options for the plugin fork-ts-checker-webpack-plugin

If you want to override path to tsconfig through pluginOptions.tsconfig the option should be specified relative to the @tramvai/cli folder itself e.g. node_modules/@tramvai/cli. By default tsconfig is expected to be in the project root directory: \<rootDir>/tsconfig.json

Deduplication of modules​

Option dedupe controls the settings of plugin for the deduplication process. Available options are:

  • "equality" - uses strict version comparison. Dedupes modules in node_modules with equal package version that are imported from different sources. E.g. imports for node_modules/package/index.js and node_modules/nested-package/node_modules/package/index.js are deduped into a single node_modules/package/index.js import whilst without dedupe it will bundle two files as separate modules.
  • "semver" - compares version of packages based on semver. It can dedupe all of the imports with the same major version and any of the minor and patch versions. E.g. next versions will be deduped: from 1.14.0 and 1.16.2 to 1.16.2, from 0.14.1 and 0.16.5 to 0.16.5, whilst versions 0.0.2 and 0.0.5 will be left without deduplication.
Production​

By default, sourcemaps are disabled both for the client and server code in production mode.

Flag --debug enables sourcemaps generation for the client and server code.

Also, tramvai.json option sourceMap enables sourcemap generation both for browser and server code.

Configuration​

Configuration is provided through json-file with the name tramvai.json in the root of the single-application/monorepo

How to​

Debug tramvai​

Debug tramvai runtime

Debug tramvai/build

Code generation​

For make life easier for developers @tramvai/cli has ability to automatically generate code with template. For running code generator use command tramvai generate and pick up one of the options available to generate that entity:

  • action
  • bundle
  • reducer
  • page
  • component
  • module

After that template files will be generated

Generate new project​

For the quick start of new project you can use command tramvai new that will generate new base project with the tramvai and tramvai-cli

  • install tramvai-cli globally
  • enter command tramvai new NAME_YOUR_APP in the shell
  • choose options based on your preferences: monorepo or multirepo, CI integration and testing framework

After command execution and dependency installation new project will be ready to use

How to use browserstack for testing​

To get access to browserstack just type command /bs in slack

Run app as usual with tramvai start command and follow the browsertack instruction for the local development. If everything were done right you will be able to get access to localhost inside browserstack and test your app through it.

How to test app on mobile or other device in local network​

Both devices one that running the app and one for testing must reside in the same network.

For setting access through local network follow next steps:

  1. figure out the ip of the machine that runs app
  2. run command tramvai start with flag --staticHost with value of the ip address that was resolved on previous step (e.g. tramvai start tincoin --staticHost 192.168.1.3)
  3. from the testing device open the new page in the browser and use the ip address from the previous step as domain name

When calling @tramvai/cli using npm you need to pass -- before any additional arguments, e.g. command should look similar to this npm start -- --staticHost 192.168.1.3

How to enable paths mapping​

In case you want to use special imports instead of pure relative paths in your code.

More details and examples you can find in typescript documentation:

@tramvai/cli will reuse options baseUrl and paths from the app's tsconfig.json to provide path mapping functionality.

How to pass Node.js options​

You can use NODE_OPTIONS env variable, e.g.:

NODE_OPTIONS="--max-semi-space-size=64" tramvai start-prod {appName}