angular-server-side-configuration
    TypeScript icon, indicating that this package has built-in type declarations

    12.0.0 • Public • Published

    angular-server-side-configuration

    Configure an angular application at runtime on the server or in a docker container via environment variables.

    Motivation

    The Angular CLI provides build time configuration (via environment.ts). In a Continuous Delivery environment this is sometimes not enough.

    How it works

    Environment variables are used for configuration. This package provides an Angular CLI builder to search for usages at build time. A native CLI can be used to insert populated environment variables into index.html file(s) into the head tag or by replacing <!--CONFIG--> (Missing environment variables will be represented by null). This should be done on the host serving the bundled angular files.

    Getting Started

    ng add angular-server-side-configuration
    

    or, if you have a previous version of this library installed

    ng update angular-server-side-configuration@latest
    

    This will configure the appropriate files.

    Alternatively, if you want to configure the files yourself:

    npm install --save angular-server-side-configuration
    

    angular.json

    Ensure you have an ngsscbuild entry in your project architect section. To use the builder run ng run your-project-name:ngsscbuild:production. You can add additional configurations in angular.json, which can be executed by replacing production with your configuration name in the previous command.

    The builder will analyze the configured ngsscEnvironmentFile to detect used environment variables and generate an ngssc.json in the defined outputPath in the referenced browserTarget.

    ...
      "projects": {
        ...
        "your-project-name": {
          ...
          "architect": {
            ...
            "ngsscbuild": {
              "builder": "angular-server-side-configuration:ngsscbuild",
              "options": {
                "additionalEnvironmentVariables": ["MANUAL_ENTRIES"],
                "browserTarget": "your-project-name:build",
                "ngsscEnvironmentFile": "src/environments/environment.prod.ts",
                // Optional
                // (Defaults to the basename of the index option of the browser target)
                "filePattern": "index.html"
              },
              "configurations": {
                "production": {
                  "browserTarget": "your-project-name:build:production"
                }
              }
            }
            ...
          }
          ...
        }
        ...
      }
    ...

    To run the ngssc build, run the command ng run your-project-name:ngsscbuild:production.

    environment.prod.ts

    angular-server-side-configuration supports two variants for using environment variables: process.env._ or NG_ENV._

    process.env.*

    Use process.env.NAME in your environment.prod.ts, where NAME is the environment variable that should be used.

    import 'angular-server-side-configuration/process';
    
    export const environment = {
      production: process.env.PROD !== 'false',
      apiAddress: process.env.API_ADDRESS || 'https://example-api.com',
    };

    NG_ENV.*

    Import NG_ENV from angular-server-side-configuration/ng-env and use NG_ENV.NAME in your environment.prod.ts, where NAME is the environment variable that should be used.

    import { NG_ENV } from 'angular-server-side-configuration/ng-env';
    
    export const environment = {
      production: NG_ENV.PROD !== 'false',
      apiAddress: NG_ENV.API_ADDRESS || 'https://example-api.com',
    };

    index.html (Optional)

    Add <!--CONFIG--> to index.html. This will be replaced by the configuration script tag. This is optional, as the environment variables can be configured to be inserted in the head tag. It is however the safest option.

    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <title>Angular Example</title>
        <!--CONFIG-->
        <base href="/" />
    
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="icon" type="image/x-icon" href="favicon.ico" />
      </head>
      <body>
        <app-root></app-root>
      </body>
    </html>

    On host server or in Dockerfile

    This library provides a Node.js and a native implementation for inserting the environment variables into your html. Either use the insert function from the package (import { insert } from 'angular-server-side-configuration';) or the insert command of the CLI. For the native CLI, go to Releases and download the appropriate executable for your server environment. (See build.sh for build details of the native CLI. Please open an Issue if you need an additional environment.)

    ngssc insert

    Usage: ngssc insert [options] [directory]

    Options Description
    -r, --recursive Recursively searches for ngssc.json files and applies the contained configuration
    --dry Perform the insert without actually inserting the variables
    Minimal Example

    Dockerfile

    FROM nginx:alpine
    
    # Install ngssc binary
    ADD https://github.com/kyubisation/angular-server-side-configuration/releases/download/v12.0.0/ngssc_64bit /usr/sbin/ngssc
    RUN chmod +x /usr/sbin/ngssc
    
    # Add ngssc init script
    COPY ngssc.sh /docker-entrypoint.d/ngssc.sh
    RUN chmod +x /docker-entrypoint.d/ngssc.sh
    
    # Copy app
    COPY dist /usr/share/nginx/html

    ngssc.sh

    #!/bin/sh
    ngssc insert /usr/share/nginx/html

    ngssc.json

    The ngssc.json will be generated by the ngsscbuild builder.

    {
      "variant": "process",           // Either "process" or "NG_ENV".
      "environmentVariables": [],     // Detected environment variables.
      "filePattern": "**/index.html"  // File pattern in which environment variables should be inserted.
    }

    License

    Apache License, Version 2.0

    Install

    npm i angular-server-side-configuration

    DownloadsWeekly Downloads

    693

    Version

    12.0.0

    License

    Apache-2.0

    Unpacked Size

    80.4 kB

    Total Files

    27

    Last publish

    Collaborators

    • kyubisation