SpotDraft Angular FrontEnd

To set up:

• Install Node (14) and NPM (included with Node)
• Increase memory available to node export NODE_OPTIONS="--max-old-space-size=8192". You might not be able to build without this.
• Install yarn npm i -g yarn
• Run npm ci

To run the server: npm start

To run tests: ng test

Repository Structure

• The repository is structured using Nx.
• The entry point (apps) are placed under /apps
• The re-usable libraries and feature libraries are placed under /libs

Python Version

To prevent errors around node-gyp you need specific Python version. It is recommended to use Pyenv to manage versions. The Python version is mentioned in .python-version file. PyEnv uses this file to figure out what version of python to use.

What about ng serve?

Unfortunately, using ng serve will always serve the default theme. So checking themes can only be done using the npm start command.

Building a production/whitelabeled image

Please see - BUILD_README.md

Folder and file structure

• The common mat config like typography has been moved to mat-commons.scss.
• Any common config/variables to be shared b/w themes should live in themes/_commons.scss

What is theme-able SVG?

To make SVG images respect theme, you can make use of theme-able-svg-images.ts script. This script will add data-theme attribute to path, rect circle, and ellipse SVG elements and sets its value to primary-${color-level} depending on fill attribute's value. This data-theme attribute is picked up by css selector defined in styles.scss and filled with theme color.

Making SVG images theme-able

// --svg-img: name of the svg file
// Note that svg-img name should have `.svg` suffix and should be placed inside src/assets

npm run set-svg-theme -- --svg-img=spotdraft.svg

Production Builds and params

To build a production image, use the ./scripts/build_and_push_fe_image.sh script. Variables for build -

• CI_COMMIT_TAG: If this tag is set, eg: qa_20190809, then the tag is used as the base path for serving the files in GCS, else the name of the branch is used.
• BASE_URL: URL for the backend. eg: https://api.dev.spotdraft.com. (notice the missing trailing slash).
• ENVIRONMENT_NAME: Used to tag the docker image. This is usually the same as the git tag.
• SD_NG_THEME: The name of theme file. Defaults to default.
• WHITELABEL_CLIENT_NAME: The provider string for whitelabel provider. See providers under whitelabel.service.ts. Defaults to NOT_WHITELABELED

Calling the build script

# A complete whitelabled build with custom theme, serving from the tag folder in GCS.

BASE_URL=https://api-nomura-uat.spotdraft.com \
SD_NG_THEME=nomura \
CI_COMMIT_TAG=nomura_20190713 \
WHITELABEL_CLIENT_NAME=NOMURA \
ENVIRONMENT_NAME=nomura_20190713 \
SD_ENVIRONMENT=PRODUCTION ./scripts/build_and_push_fe_image.sh

Using the build scripts and config files

To make it even simpler to build recurring configs (prod, qa, nomura etc.), you can use the builder.ts script along with one of the build configs stored under the scripts/build_profiles. These have all static variables (theme, url, whitelabel etc.) pre-configured.

To use the builder script -

Requirements -

1. Git
2. Docker
3. A valid GCS credentials file to be able to push to the deployment bucket. Set the GOOGLE_AUTH_KEY_FILE environment variable to the path of the credentials file.

// --build: name of the build config.
// --docker-tag: tag of the docker image
// --tag: Git tag (This serves as the folder for deployment under GCS)
// Note the extra -- before the flags. That is required by npm to pass the flags from the run command to the script inside.

npm run build-config -- --build=nomura --docker-tag=nomura_date --tag=nomura_date

Sample Build file

A build file is a simple json with the following data -

{
  "base_url": "https://api.spotdraft.com",
  "whitelabeled": "NONE",
  "theme": "default"
}

Editor and Plugins Setup

Same-Origin Setup [Important]

Some functionality requires us to hook into the iframe of the editor itself. Since the script that loads the iframe is a remote server and local development happens over localhost the Same-Origin policy prevents us from accessing the iframe.

Please follow the steps below to serve both local environment and remote server under the same origin

Proxrox

Proxrox is a tool that runs nginx under different temporary configurations. To setup proxrox, please follow the instructions here. You only need to install nginx and proxrox.

Once you have installed proxrox, from the project directory, run - proxrox start .proxrox.yaml

By using proxrox, we are making nginx redirect localhost/ to localhost:3000.

Update the hosts file.

## sudo is required
sudo nano /etc/hosts
## add the line below to the end of the file
127.0.0.1 local.dev.spotdraft.com
## Make sure that there is an empty line at the end of the file.

Now, open local.dev.spotdraft.com in your browser, it should load localhost.

Note:

1. www.local.dev.spotdraft.com will not work.

Choosing the right proxrox config

There are four proxrox config files that can be switched between as per the development requirement. This is done to enable efficient developemnt environment setup by only running services that are required at any point of time.

1. proxrox.yaml - Remote plugins and remote onlyoffice -- When not developing anything related to editor/plugins
2. proxrox.dev.editor.yaml - Remote plugins and local onlyoffice
3. proxrox.dev.plugins.yaml - Local plugins and remote onlyoffice
4. proxrox.dev.yaml - Local plugins and local onlyoffice

How are we making tests run faster in CI?

Isolated Modules option

By default ts-jest uses TypeScript compiler in the context of a project, with full type-checking and features. But it can also be used to compile each file separately, what TypeScript calls an ‘isolated module’. That’s what the isolatedModules option (which defaults to false) does.

You’ll lose type-checking ability and some features but, your tests will then run much faster.

How are we configuring this in our projects?

We want to set isolatedModules option to true in only CI pipeline, so we rely on GitHub variable CI to check whether tests are running in CI and only then set it to true.

Example

// jest.config.ts of your project
export default {
  displayName: "my-project",
  // [...],
  transform: {
    isolatedModules: process.env["CI"] ?? false,
    "^.+\\.(ts|mjs|js|html)$": [
      "jest-preset-angular",
      {
        tsconfig: "<rootDir>/tsconfig.spec.json",
        stringifyContentPathRegex: "\\.(html|svg)$"
      }
    ]
  }
  // [...]
};

What about new projects that are going to be created?

We are adding a custom Nx generator that will take care of setting isolatedModules property when creating a new project.

Recommended VS Code Extensions

• Angular Language Service - https://marketplace.visualstudio.com/items?itemName=Angular.ng-template
• Prettier (HTML/JS Formatting) - https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
• TSLint - https://marketplace.visualstudio.com/items?itemName=eg2.tslint
• TS Move - https://marketplace.visualstudio.com/items?itemName=stringham.move-ts
• DraftKit Intellisense - provides SpotDraft specific auto-complete for CSS utils.
• Nx Console - https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console