Recommended Development Environment

Note: Spartacus 2.x is no longer maintained. Please upgrade to the latest version.

CLI tools

There are a number of necessary CLI tools that you need to have installed in order to work with Spartacus, as follows:

• Node - first and foremost you need Node installed. To install it, refer to the official site. An alternative to installing a system-wide version of node is to use a Node version manager, such as nvm. nvm also works on Windows via Windows Subsystem for Linux, a.k.a. WSL; if WSL is not available, nvm-windows can be used. The advantage of installing a Node version manager is that it provides an ability to easily switch to a different version of Node.
• Package manager - Spartacus team prefers yarn over npm, as a package manager solution, for its speed. To install yarn see the official guide. npm comes pre-installed with Node.
• Angular CLI - to install it, run npm install -g @angular/cli. To configure angular CLI to always use yarn over npm run ng config -g cli.packageManager yarn. This setting is stored in <YOUR_HOMEDIR>/.angular-config.json. For more, see this article.

Versions

Your Angular development environment should include the following:

• Angular CLI: Version 9.1 or later, < 10.0.
• Node.js: The most recent 12.x version is recommended, < 13.
• Yarn: Version 1.15 or later.

Editor

Spartacus team recommends a highly extensible and open source editor - VSCode, which can be downloaded from here.

VSCode settings

To share some common settings across team members, create .vscode folder in the root of your project, and inside of it create settings.json file. Settings added here are known as workspace settings.

Here are some recommended workspace settings that also help to avoid collision with the recommended code-formatter:

{
  // Prettier uses single quotes.
  "prettier.singleQuote": true,
  // Prettify on save
  "editor.formatOnSave": true,
  // prettier uses 2 spaces instead of 4
  "editor.tabSize": 2,
  // organize imports on save
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  // Uses the project specific typescript version.
  "typescript.tsdk": "node_modules/typescript/lib"
}

VSCode extensions

Here is a list of recommended extensions when working with Spartacus:

• angular language services
• chrome debugger
• TSLint
• prettier - code formatter

There’s no need to manually install these extensions - just create .vscode folder in the root of your project, and inside of it create extensions.json with the following content:

{
  "recommendations": [
    // Angular Language Service
    "Angular.ng-template",
    // Debugger for Chrome
    "msjsdiag.debugger-for-chrome",
    // The ng lint command uses TSLint under the hood.
    "ms-vscode.vscode-typescript-tslint-plugin",
    // Prettier - Code formatter
    "esbenp.prettier-vscode"
  ]
}

VSCode will automatically prompt you to install the recommended extensions with just one click. This is also a nice way to have a consistent environment across team members.

Some other notable extensions:

• Inline HTML and CSS highlighter - natewallace.angular2-inline
• A more richer git support than VS Code’s default one - eamodio.gitlens
• AI assisted IntelliSense - visualstudioexptteam.vscodeintellicode
• Docker support - peterjausovec.vscode-docker
• Languages support for the SAP Hybris import/export language ImpEx (unofficial) - simplyroba.impex-support
• Markdown linting and style checking for Visual Studio Code - davidanson.vscode-markdownlint

Project setup

After creating a new project and pulling Spartacus libraries, it’s time to set up the project.

Code formatting

As a code formatter, Spartacus team prefers prettier. To install it as a dependency, run yarn add prettier --dev. To share prettier settings with all team members, create .prettierrc file in the root of your project and paste the following:

{
  "printWidth": 120,
  "singleQuote": true,
  "useTabs": false,
  "tabWidth": 2,
  "semi": true,
  "bracketSpacing": true,
  "trailingComma": "es5"
}

Most of these options are prettier’s defaults, but it’s a good practice to have them explicitly defined.

To ignore some files from being formatted, create .prettierignore in the project’s root, and ignore your files like so:

**/*.md

To avoid collision between tslint and prettier, it’s recommended to remove formatting rules from the tslint.json and leave the formatting to prettier. This is a diff version of rules that should be removed from the tslint.json:

{
  "rulesDirectory": [
    "node_modules/codelyzer"
  ],
  "rules": {
    "arrow-return-shorthand": true,
    "callable-types": true,
    "class-name": true,
--  "comment-format": [
--    true,
--    "check-space"
--   ],
--  "curly": true,
--  "eofline": true,
    "forin": true,
    "import-blacklist": [
      true,
      "rxjs",
      "rxjs/Rx"
    ],
--  "import-spacing": true,
--  "indent": [
--    true,
--    "spaces"
--  ],
    "interface-over-type-literal": true,
    "label-position": true,
--  "max-line-length": [
--    true,
--    140
--  ],
    "member-access": false,
    "member-ordering": [
      true,
      {
        "order": [
          "static-field",
          "instance-field",
          "static-method",
          "instance-method"
        ]
      }
    ],
    "no-arg": true,
    "no-bitwise": true,
    "no-console": [
      true,
      "debug",
      "info",
      "time",
      "timeEnd",
      "trace"
    ],
    "no-construct": true,
    "no-debugger": true,
    "no-duplicate-super": true,
    "no-empty": false,
    "no-empty-interface": true,
    "no-eval": true,
    "no-inferrable-types": [
      true,
      "ignore-params"
    ],
    "no-misused-new": true,
    "no-non-null-assertion": true,
    "no-shadowed-variable": true,
    "no-string-literal": false,
    "no-string-throw": true,
    "no-switch-case-fall-through": true,
--  "no-trailing-whitespace": true,
    "no-unnecessary-initializer": true,
    "no-unused-expression": true,
    "no-use-before-declare": true,
    "no-var-keyword": true,
    "object-literal-sort-keys": false,
--  "one-line": [
--    true,
--    "check-open-brace",
--    "check-catch",
--    "check-else",
--    "check-whitespace"
--  ],
    "prefer-const": true,
--  "quotemark": [
--    true,
--    "single"
--  ],
    "radix": true,
--  "semicolon": [
--    true,
--    "always"
--  ],
    "triple-equals": [
      true,
      "allow-null-check"
    ],
--  "typedef-whitespace": [
--    true,
--    {
--      "call-signature": "nospace",
--      "index-signature": "nospace",
--      "parameter": "nospace",
--      "property-declaration": "nospace",
--      "variable-declaration": "nospace"
--    }
--  ],
    "typeof-compare": true,
    "unified-signatures": true,
    "variable-name": false,
 -- "whitespace": [
 --   true,
 --   "check-branch",
 --   "check-decl",
 --   "check-operator",
 --   "check-separator",
 --   "check-type"
 -- ],
    "directive-selector": [
      true,
      "attribute",
      "app",
      "camelCase"
    ],
    "component-selector": [
      true,
      "element",
      "app",
      "kebab-case"
    ],
--  "angular-whitespace": [true, "check-interpolation"],
    "no-output-on-prefix": true,
    "use-input-property-decorator": true,
    "use-output-property-decorator": true,
    "use-host-property-decorator": true,
    "no-input-rename": true,
    "no-output-rename": true,
    "use-life-cycle-interface": true,
    "use-pipe-transform-interface": true,
    "component-class-suffix": true,
    "directive-class-suffix": true
  }
}

You can read more in this article.

To run prettier you can add this script to package.json to scripts array: "prettier": "prettier --config ./.prettierrc --list-different \"src/**/*{.ts,.js,.json,.scss,.html}\"".

Note: you may have to change src to match the directory that you are using as a source directory.

To check for formatting violations run: yarn prettier.

linting

To check for linting violations, run ng lint.

To improve linting, add the following to the tsconfig.json located in the project’s root:

  "noUnusedLocals": true,
  "noUnusedParameters": true,

git ignore

If you switched from using npm to yarn, it’s wise to delete package-lock.json file that npm generates, and add this file to .gitignore:

package-lock.json

Final Steps

Finally, you may need to run yarn install to install dependencies added to package.json.