DEV Community: Bo Vandersteene

Runtime Environment Variables in Frontend Applications

Bo Vandersteene — Wed, 28 Jan 2026 09:07:58 +0000

Runtime Environment Variables in Frontend Applications

When deploying frontend applications with Docker, environment variables require special handling. This is because bundlers like Vite, Webpack, and esbuild resolve environment variables at build time, not at runtime.

Since environment variables typically differ per environment (DEV, TST, QAS, PRD), we need a runtime solution that allows us to build once, deploy everywhere.

This guide shows how to inject environment variables at container startup using a config.json file that your application fetches at runtime.

How It Works

Build phase: Your app is built without environment-specific values
Container startup: A shell script generates config.json from environment variables
App initialization: Your frontend fetches config.json before rendering

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   Docker Build  │      │ Container Start │      │   App Loads     │
│                 │      │                 │      │                 │
│  npm run build  │ ──▶  │ entrypoint.sh   │ ──▶  │ fetch config.json│
│  (no env vars)  │      │ creates config  │      │ then render     │
└─────────────────┘      └─────────────────┘      └─────────────────┘

Docker Configuration

docker-entrypoint.sh

This is the heart of the runtime configuration system. The entrypoint script runs each time the container starts, generating a fresh config.json file from the current environment variables.

Key benefits:

No rebuild required when configuration changes
Just restart the container to pick up new values
Works with any orchestration system (Kubernetes, Docker Compose, etc.)

#!/bin/sh
set -e

# Generate runtime config from environment variables
# This file will be served by your web server and fetched by the app at startup
#
# The heredoc (<<EOF) creates the JSON file inline
# Shell variables like ${API_URL} are expanded when the script runs
cat > /srv/config.json <<EOF
{
  "API_URL": "${API_URL}",
  "AUTH_URL": "${AUTH_URL}",
  "FEATURE_FLAGS": "${FEATURE_FLAGS}",
  "ENV": "${ENV}"
}
EOF
# NOTE: Add any additional environment variables you need above
# Make sure to also update your config interface/type in the frontend code
#
# TIP: For optional variables with defaults, you can use:
#   "TIMEOUT": "${TIMEOUT:-5000}"
# This sets TIMEOUT to 5000 if the environment variable is not set

echo "Generated /srv/config.json with runtime configuration"

# Start Caddy as the main process
# Using 'exec' replaces the shell process with Caddy, which:
#   - Ensures proper signal handling (SIGTERM, SIGINT)
#   - Makes Caddy PID 1 in the container
#   - Allows graceful shutdown to work correctly
exec caddy run --config /etc/caddy/Caddyfile --adapter caddyfile

Dockerfile

This Dockerfile uses a multi-stage build pattern to create a small, production-ready image. The first stage builds the application, and the second stage contains only the built assets and the web server.

Why multi-stage builds?

Keeps the final image small (no node_modules, no build tools)
Separates build-time dependencies from runtime
Improves security by reducing attack surface

# =============================================================================
# Stage 1: Build the frontend application
# =============================================================================
FROM node:23-alpine AS builder
WORKDIR /app

# Enable pnpm via corepack (built into Node.js)
# Replace with npm/yarn if preferred:
#   npm: Remove these lines entirely
#   yarn: RUN corepack enable && corepack prepare yarn@stable --activate
RUN corepack enable && corepack prepare pnpm@latest --activate

# Copy package files first for better layer caching
# Docker caches each layer, so if package.json hasn't changed,
# the dependency installation step is skipped on subsequent builds
COPY package.json pnpm-lock.yaml* ./

# Install all dependencies (including devDependencies needed for build)
# Use --frozen-lockfile in CI to ensure reproducible builds:
#   RUN pnpm install --frozen-lockfile
RUN pnpm install

# Copy source code and build the production bundle
# This step is only re-run when source files change
COPY . .
RUN pnpm run build

# =============================================================================
# Stage 2: Production image with Caddy
# =============================================================================
FROM caddy:alpine

# Copy built assets from builder stage
# Adjust /app/dist to match your framework's output directory:
#   - Vue/Vite: /app/dist
#   - React (CRA): /app/build
#   - Angular: /app/dist/<project-name>
#   - Next.js (static): /app/out
COPY --from=builder /app/dist /srv

# Copy Caddy configuration
COPY Caddyfile /etc/caddy/Caddyfile

# Copy and prepare the entrypoint script
# This script generates config.json from environment variables at runtime
COPY docker-entrypoint.sh /docker-entrypoint.sh
RUN chmod +x /docker-entrypoint.sh

# Default port (can be overridden via environment variable)
# This is just documentation and a default; the actual port is set in Caddyfile
ENV PORT=9000

# Document which port the container listens on
EXPOSE ${PORT}

# Use the entrypoint script to generate config before starting Caddy
# ENTRYPOINT runs before CMD, making it perfect for initialization tasks
ENTRYPOINT ["/docker-entrypoint.sh"]

Caddyfile

Caddy is a modern web server with automatic HTTPS and simple configuration. This Caddyfile configures it to serve a Single Page Application (SPA) with client-side routing support.

Why Caddy?

Zero-config HTTPS with automatic certificate management
Simple, readable configuration syntax
Small footprint, perfect for containers
Built-in compression and modern HTTP features

# Listen on the configured port
# The {$PORT} syntax reads from environment variables
:{$PORT}

# Serve static files from /srv
# This is where our built frontend assets live
root * /srv

# Enable gzip compression for text-based files
# Significantly reduces transfer size for JS, CSS, HTML, and JSON
encode gzip

# Serve static files with appropriate MIME types
file_server

# SPA fallback: serve index.html for routes not matching a file
# This is essential for client-side routing (Vue Router, React Router, etc.)
#
# Without this, refreshing on /dashboard would return 404
# because there's no physical /dashboard file
#
# How it works:
#   1. Try to serve the exact path requested
#   2. If no file exists, serve index.html instead
#   3. The frontend router then handles the route
try_files {path} /index.html

Frontend Implementation

Configuration Interface

Before implementing the config loader, define a TypeScript interface that describes your configuration shape. This provides type safety and autocompletion throughout your application.

Best practices:

Keep this interface in sync with your docker-entrypoint.sh
Use union types for known values (like environment names)
Add JSDoc comments for complex configuration options

/**
 * Runtime configuration interface
 * Update this interface when adding new environment variables
 *
 * This interface should match the JSON structure generated
 * by docker-entrypoint.sh
 */
export interface RuntimeConfig {
  /** Base URL for backend API requests (e.g., "https://api.example.com") */
  API_URL: string;

  /** Authentication service URL for OAuth/OIDC flows */
  AUTH_URL: string;

  /** Comma-separated list of enabled feature flags */
  FEATURE_FLAGS: string;

  /** Current deployment environment */
  ENV: "DEV" | "TST" | "QAS" | "PRD";
}

runtime-config.ts

This is the core configuration loader used by all frameworks. It fetches the config.json file generated by the Docker entrypoint and caches it for synchronous access throughout your application.

Important: Call loadRuntimeConfig() during application startup, before any code that needs configuration values. This ensures the config is loaded and cached before getRuntimeConfig() is called.

Why this pattern?

Single fetch at startup, then synchronous access everywhere
No need to pass config through props or context (though you can)
Works with any framework or vanilla JavaScript
Fails fast if config is missing

export interface RuntimeConfig {
  API_URL: string;
  AUTH_URL: string;
  FEATURE_FLAGS: string;
  ENV: "DEV" | "TST" | "QAS" | "PRD";
}

// Cache the config after first load to avoid repeated fetches
// Using module-level variable ensures single source of truth
let cachedConfig: RuntimeConfig | null = null;

/**
 * Loads the runtime configuration from config.json
 * This file is generated by docker-entrypoint.sh at container startup
 *
 * @returns Promise resolving to the runtime configuration
 * @throws Error if config cannot be loaded (network error, invalid JSON, etc.)
 *
 * @example
 * // Call once at app startup
 * await loadRuntimeConfig();
 *
 * // Then use getRuntimeConfig() anywhere
 * const config = getRuntimeConfig();
 */
export async function loadRuntimeConfig(): Promise<RuntimeConfig> {
  // Return cached config if already loaded
  // This makes subsequent calls instant and prevents race conditions
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Use BASE_URL to support apps deployed at subpaths (e.g., /my-app/)
    // Vite sets this based on the `base` option in vite.config.ts
    // Falls back to "/" for root deployments
    const baseUrl = import.meta.env.BASE_URL || "/";
    const response = await fetch(`${baseUrl}config.json`);

    // Check for HTTP errors (404, 500, etc.)
    if (!response.ok) {
      throw new Error(`Failed to load config: ${response.status}`);
    }

    // Parse and cache the configuration
    // The non-null assertion (!) is safe because we just set it
    cachedConfig = await response.json();
    return cachedConfig!;
  } catch (error) {
    // Log the error for debugging, then re-throw
    // This ensures the app doesn't silently fail with missing config
    console.error("Failed to load runtime config:", error);
    throw new Error("Failed to load runtime config");
  }
}

/**
 * Synchronously retrieves the cached runtime configuration
 * Must call loadRuntimeConfig() before using this function
 *
 * @returns The cached runtime configuration
 * @throws Error if config has not been loaded yet
 *
 * @example
 * // In any component or service (after loadRuntimeConfig has been called)
 * const config = getRuntimeConfig();
 * console.log(config.API_URL);
 */
export function getRuntimeConfig(): RuntimeConfig {
  // Fail fast with a clear error message if config wasn't loaded
  // This catches programming errors where getRuntimeConfig is called too early
  if (!cachedConfig) {
    throw new Error(
      "Runtime config not loaded. Call loadRuntimeConfig() first."
    );
  }
  return cachedConfig;
}

Native JavaScript

For vanilla JavaScript applications or simple static sites without a framework. This approach works with any bundler (Vite, Webpack, Rollup) or even without one.

When to use:

Simple static sites
Legacy applications
Micro-frontends
When you don't need a framework

main.js

import { loadRuntimeConfig, getRuntimeConfig } from "./runtime-config.js";

// Load config before initializing the application
// The promise chain ensures config is ready before any app code runs
loadRuntimeConfig()
  .then(() => {
    // Config is now loaded and cached
    const config = getRuntimeConfig();
    console.log(`Running in ${config.ENV} environment`);
    console.log(`API endpoint: ${config.API_URL}`);

    // Initialize your application here
    // At this point, getRuntimeConfig() can be called from anywhere
    initApp();
  })
  .catch((error) => {
    // Handle config loading failure gracefully
    // This might happen if config.json is missing or malformed
    console.error("Failed to initialize app:", error);

    // Show a user-friendly error message
    // In production, you might want a more polished error page
    document.body.innerHTML = `
      <div style="padding: 20px; text-align: center;">
        <h1>Configuration Error</h1>
        <p>Failed to load application configuration. Please try refreshing the page.</p>
      </div>
    `;
  });

/**
 * Initialize your application
 * Called after config is successfully loaded
 */
function initApp() {
  const config = getRuntimeConfig();

  // Example: Set up API client with base URL
  // window.apiClient = new ApiClient(config.API_URL);

  // Example: Initialize feature flags
  // window.features = parseFeatureFlags(config.FEATURE_FLAGS);

  // Your application initialization code here
}

Vue

Vue applications load the configuration before mounting the app to the DOM. This ensures all components have access to configuration from the moment they're created.

Key points:

Load config in main.ts before app.mount()
Access config in components via getRuntimeConfig()
No need for Vuex/Pinia for simple config access

main.ts

import { createApp } from "vue";
import App from "./App.vue";
import { loadRuntimeConfig } from "./config/runtime-config";

// Create the Vue app instance
// We create it early but don't mount until config is loaded
const app = createApp(App);

// Load runtime config before mounting the app
// This ensures config is available to all components from the start
loadRuntimeConfig()
  .then(() => {
    // Config loaded successfully, now it's safe to mount the app
    // All components can now use getRuntimeConfig() in their setup/created hooks
    app.mount("#app");
  })
  .catch((error) => {
    // Handle config loading failure gracefully
    // Log the error for debugging purposes
    console.error("Failed to initialize app:", error);

    // Show an error message to the user
    // The non-null assertion is safe because #app exists in index.html
    document.getElementById("app")!.innerHTML = `
      <div style="padding: 20px; text-align: center;">
        <h1>Configuration Error</h1>
        <p>Failed to load configuration. Please refresh the page.</p>
      </div>
    `;
  });

Usage in Components

Once the app is mounted, any component can access the configuration synchronously using getRuntimeConfig().

<script setup lang="ts">
import { getRuntimeConfig } from "@/config/runtime-config";

// Access config in any component after app initialization
// This is safe because main.ts ensures config is loaded before mount
const config = getRuntimeConfig();

// Example: Use config values
const apiUrl = config.API_URL;
const isDev = config.ENV === "DEV";

// Example: Conditional feature based on environment
const showDebugTools = config.ENV !== "PRD";
</script>

<template>
  <div>
    <p>Current environment: {{ config.ENV }}</p>
    <p>API URL: {{ config.API_URL }}</p>

    <!-- Conditionally show debug info in non-production -->
    <pre v-if="showDebugTools">{{ JSON.stringify(config, null, 2) }}</pre>
  </div>
</template>

React

React applications load configuration before calling ReactDOM.createRoot().render(). This pattern ensures the entire component tree has access to configuration.

Key points:

Load config in index.tsx before rendering
Use getRuntimeConfig() directly in components, or
Wrap with Context for better testability and React patterns

index.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import { loadRuntimeConfig } from "./config/runtime-config";

// Get the root element from index.html
// The non-null assertion is safe because this element must exist
const rootElement = document.getElementById("root")!;
const root = ReactDOM.createRoot(rootElement);

// Load runtime config before rendering the app
// This ensures config is available to all components from the first render
loadRuntimeConfig()
  .then(() => {
    // Config loaded successfully, render the app
    // StrictMode helps catch common issues during development
    root.render(
      <React.StrictMode>
        <App />
      </React.StrictMode>
    );
  })
  .catch((error) => {
    // Handle config loading failure gracefully
    console.error("Failed to initialize app:", error);

    // Render an error message instead of the app
    // In production, you might want a more polished error boundary
    root.render(
      <div style={{ padding: "20px", textAlign: "center" }}>
        <h1>Configuration Error</h1>
        <p>Failed to load application configuration. Please refresh the page.</p>
      </div>
    );
  });

Usage with Context (Optional)

For better React integration and testability, you can wrap the configuration in a Context. This makes it easy to mock config in tests and follows React patterns.

Benefits of using Context:

Easier to test (mock the provider)
Better React DevTools integration
Follows React's data flow patterns
Type-safe hook with clear error messages

import React, { createContext, useContext, ReactNode } from "react";
import { RuntimeConfig, getRuntimeConfig } from "./runtime-config";

// Create context with undefined default
// We use undefined (not null) to distinguish "not provided" from "explicitly null"
const ConfigContext = createContext<RuntimeConfig | undefined>(undefined);

/**
 * Provider component that supplies runtime config to the component tree
 *
 * IMPORTANT: Only use this after loadRuntimeConfig() has resolved
 * Typically wrap your App component with this in index.tsx
 *
 * @example
 * root.render(
 *   <ConfigProvider>
 *     <App />
 *   </ConfigProvider>
 * );
 */
export function ConfigProvider({ children }: { children: ReactNode }) {
  // Safe to call since we load config before rendering
  // If this throws, it means ConfigProvider was used before config loaded
  const config = getRuntimeConfig();

  return (
    <ConfigContext.Provider value={config}>{children}</ConfigContext.Provider>
  );
}

/**
 * Hook to access runtime configuration in components
 *
 * @returns The runtime configuration object
 * @throws Error if used outside of ConfigProvider
 *
 * @example
 * function MyComponent() {
 *   const config = useConfig();
 *   return <div>Environment: {config.ENV}</div>;
 * }
 */
export function useConfig(): RuntimeConfig {
  const config = useContext(ConfigContext);

  // Provide a helpful error message if used incorrectly
  if (!config) {
    throw new Error("useConfig must be used within a ConfigProvider");
  }

  return config;
}

Usage in Components

Components can access configuration either through the hook (if using Context) or directly via getRuntimeConfig().

import { useConfig } from "./config/ConfigContext";
// Or directly (if not using context):
// import { getRuntimeConfig } from './config/runtime-config';

/**
 * Example component showing config usage
 */
function MyComponent() {
  // Option 1: Using the hook (recommended if using Context)
  const config = useConfig();

  // Option 2: Direct access (simpler, but harder to test)
  // const config = getRuntimeConfig();

  // Example: Conditional rendering based on environment
  const showDebugInfo = config.ENV === "DEV";

  return (
    <div>
      <p>Current environment: {config.ENV}</p>
      <p>API URL: {config.API_URL}</p>

      {/* Only show in development */}
      {showDebugInfo && (
        <details>
          <summary>Debug Info</summary>
          <pre>{JSON.stringify(config, null, 2)}</pre>
        </details>
      )}
    </div>
  );
}

export default MyComponent;

Angular

Angular uses the APP_INITIALIZER token to run code before the application bootstraps. This is the idiomatic way to load configuration in Angular applications.

Key points:

APP_INITIALIZER delays bootstrap until the Promise resolves
Works with both standalone components (Angular 17+) and NgModules
Configuration is available to all services and components from the start

app.config.ts (Angular 17+ standalone)

Angular 17 introduced a new standalone application architecture. Use this approach for new Angular applications.

import { ApplicationConfig, APP_INITIALIZER } from "@angular/core";
import { loadRuntimeConfig } from "./config/runtime-config";

/**
 * Factory function for APP_INITIALIZER
 *
 * Returns a function that loads the runtime config
 * Angular waits for the returned Promise to resolve before bootstrapping
 *
 * Note: The factory function returns another function (not a Promise directly)
 * This allows Angular to control when the initialization runs
 */
function initializeApp() {
  // Return a function that returns a Promise
  // Angular will call this function and wait for the Promise
  return () => loadRuntimeConfig();
}

/**
 * Application configuration
 * Passed to bootstrapApplication() in main.ts
 */
export const appConfig: ApplicationConfig = {
  providers: [
    // Register the APP_INITIALIZER to load config before app starts
    // Angular will wait for this to complete before rendering any components
    {
      provide: APP_INITIALIZER,
      useFactory: initializeApp,
      multi: true, // Allows multiple initializers to run in parallel
    },
    // Add other providers here (router, http, etc.)
  ],
};

app.module.ts (Angular with NgModules)

For existing Angular applications using the traditional NgModule architecture.

import { NgModule, APP_INITIALIZER } from "@angular/core";
import { BrowserModule } from "@angular/platform-browser";
import { AppComponent } from "./app.component";
import { loadRuntimeConfig } from "./config/runtime-config";

/**
 * Factory function for APP_INITIALIZER
 *
 * Returns a function that loads the runtime config
 * The returned function must return a Promise
 */
function initializeApp() {
  return () => loadRuntimeConfig();
}

@NgModule({
  // Declare components that belong to this module
  declarations: [AppComponent],

  // Import other modules this module depends on
  imports: [BrowserModule],

  // Configure dependency injection
  providers: [
    // Register the APP_INITIALIZER to load config before app starts
    {
      provide: APP_INITIALIZER,
      useFactory: initializeApp,
      // Note: No deps needed since we're using the standalone loadRuntimeConfig
      multi: true, // Allows multiple initializers
    },
  ],

  // The root component to bootstrap
  bootstrap: [AppComponent],
})
export class AppModule {}

Usage in Components

After the app initializes, any component can access the configuration using getRuntimeConfig().

import { Component } from "@angular/core";
import { getRuntimeConfig, RuntimeConfig } from "./config/runtime-config";

/**
 * Example component demonstrating config access
 *
 * The config is guaranteed to be loaded because APP_INITIALIZER
 * runs before any components are created
 */
@Component({
  selector: "app-example",
  template: `
    <div>
      <p>Current environment: {{ config.ENV }}</p>
      <p>API URL: {{ config.API_URL }}</p>

      <!-- Conditional content based on environment -->
      <div *ngIf="isDevelopment" class="debug-panel">
        <h3>Debug Info</h3>
        <pre>{{ config | json }}</pre>
      </div>
    </div>
  `,
})
export class ExampleComponent {
  // Load config once when component is created
  // Safe to call synchronously because APP_INITIALIZER has already run
  config: RuntimeConfig = getRuntimeConfig();

  // Computed property for template use
  get isDevelopment(): boolean {
    return this.config.ENV === "DEV";
  }
}

Summary

Component	Purpose
`docker-entrypoint.sh`	Generates `config.json` from env vars at startup
`Dockerfile`	Multi-stage build with Caddy for serving
`Caddyfile`	Web server config with SPA routing support
`runtime-config.ts`	Fetches and caches runtime config in your app
`main.ts / index.tsx`	Loads config before app initialization

Framework-Specific Notes

Framework	Build Output Dir	Base URL Variable	Init Location
Vue (Vite)	`dist`	`import.meta.env.BASE_URL`	`main.ts`
React CRA	`build`	`process.env.PUBLIC_URL`	`index.tsx`
React Vite	`dist`	`import.meta.env.BASE_URL`	`index.tsx`
Angular	`dist/<project-name>`	Set in `angular.json` baseHref	`app.config.ts`
Native JS	varies	`/` or configure manually	`main.js`

Troubleshooting

Config not loading

Check that config.json exists in the served directory (/srv/)
Verify the entrypoint script has execute permissions (chmod +x)
Check browser console for fetch errors (404, CORS, etc.)

Environment variables not appearing

Ensure variables are passed to the container (docker run -e VAR=value)
Check the generated config.json inside the container
Verify variable names match between entrypoint and interface

SPA routing not working

Confirm try_files {path} /index.html is in your Caddyfile
Check that the web server is actually serving index.html for unknown routes

This approach allows you to build your application once and deploy it to multiple environments, with configuration injected at runtime via environment variables.

Use table to validate your Unit tests with Jest

Bo Vandersteene — Tue, 04 Aug 2020 07:40:58 +0000

Some years ago (2017) I discovered Jest.
But what is Jest:
Jest is a delightful JavaScript Testing Framework with a focus on simplicity.
More information on jest.io

In this blog post I will not explain what jest is, but I will explain one of the features I really love: Using tables to test your code. You can build a test matrix, and then just run it through your code

Example

We have this code snippet that we want to test. As you see there can be 3 cases to test,

function calculate(a: number, b: number): number {
    if (a < b) return a + b;
    if (a === b) return a * b;
    return a - b;
}

How we are used to do it.

With Jasmine our Jest we would write a test that looks like something bellow.

test('calculate(2, 3) should return 5', () => {
    expect(calculate(2, 3)).toBe(5);
});

test('calculate(3, 2) should return 1', () => {
    expect(calculate(3,2)).toBe(1);
});

test('calculate(3, 3) should return 9', () => {
    expect(calculate(3, 3)).toBe(9);
});

We define the different test cases, and just write some tests for it.

But if we need to cover more test cases, then we will end up in copy pasting all these cases again and again.
Maybe we forget to update the description and finally we will end up in test cases that are no longer correct.

Add arrays that contains the test cases

Another option is to compose an array, with an array.

[[2, 3, 5] 
[3, 2, 1]
[3, 3, 9]]

Then we write our test while looping over the result

test.each([[2, 3, 5], [3, 2, 1], [3, 3, 9]])
('calculate(%i, %i) should return $expected', (a, b, expected) => {
    expect(calculate(a, b)).toBe(expected);
});

But again this is not maintainable and hard to read.

Also if you read the test again, you don’t know what the first value want to say, or how many values we should have.
Testing should be the documentation of your code
If we want to use the tests as the documentation of our code, then we need to make sure that the tests are readable and maintainable.
But we can use another solution in Jest, let’s look at a table

Add a table that contains the test results

But in fact our test data is a table:
| a | b | expected |
| 2 | 3 | 5 |
| 3 | 2 | 1 |
| 3 | 3 | 9 |

A table would be more readable for our code, also extending the test results would be much easier
We could write our tests as bellow

test.each`
  a    | b    | expected
  ${2} | ${3} | ${5}
  ${3} | ${2} | ${1}
  ${3} | ${3} | ${9}
`('calculate($a, $b) should return $expected', ({ a, b, expected }) => {
  expect(a + b).toBe(expected);
});

And we could go further. We are working with typescript, so we want to add some type checking. We can define the type of our TestData just before and make more complicated test cases.

interface TestData {
  a: number, 
  b: number,
  expected: number
}
test.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('calculate($a, $b) should return $expected', ({ a, b, expected }: TestData) => {
  expect(a + b).toBe(expected);
});

Create a reusable angular service

Bo Vandersteene — Tue, 14 Jan 2020 08:29:30 +0000

Create a reusable angular service

The goal is to create a service that can be reused throughout our Angular application.
The different kind of use cases this service would be usefull for would be like:

Call different APIs that return the same output format
Use different settings for that service
Have a local state inside the service, and that state should be different amongst different use cases
…

The most common way of using a service

By default we use services through dependency injection. Registering a dependency can be done in multiple ways.

Globally using provideIn: 'root' metadata on the service @Injectable decorator
On module level in the providers array of the module
On component level in the providers array of the component

Now let's create a service that we're not going to inject on the root level.
In this case we will inject it into the module.

For the purpose of the example a simple service is created.

@Injectable()
export class ReuseService {
  name: string = 'reuse me!'; 
}

Provide the service on module level.

@NgModule({
  // imports, declarations, ....
  providers: [ReuseService]
})
export class AppModule { }

And use it in you're component

@Component({
  selector: 'my-app',
  template: ` 
  <ul>
    <li>reuseService: {{reuseService.name}}</li>
  </ul>
  ` 
})
export class AppComponent  { 
  constructor(public reuseService: ReuseService ){}
}

But now it turns out that the name should be set outside the service…

Use a factory

Factory’s are used to create a service dynamically. Sometime a value that we use inside the service don’t have exist until run time.

To use a factory inside angular, a factory provider should be created. This can be done through a function.

The reuseFactory, is responsible to get the name from somewhere else so the factory function looks as following:

// create the factory
export function reuseFactory(name: string){
  return () => new ReuseService(name)
}

Now we want to give the responsibility of setting the name to our module. This can be done with a factory.

@NgModule({
  // imports, declarations, ....
  providers: [
    // Provide you're service through a factory
    {
      provide: ReuseService,
      useFactory: reuseFactory("reuse service")
    },
 ]
})
export class AppModule { }

In this example we only inject a string, but it can also be an other provider.

More information on how to use factory providers: Angular Docs - factory providers

Create Injection Tokens

An injection token can be used in a DI provider. It can be used also to create unique names for service. Create a token.ts file and give an unique name for the token

export const REUSE  = new InjectionToken<ReuseService>('ReuseService1');

The token can be used in the provider section of the factory


@NgModule({
  // imports, declarations, ....
  providers: [ 
    {
      // use token instead of service class
      provide: REUSE,
      useFactory: reuseFactory("reuse service")
    }   
    ]
})
export class AppModule {}

Now the injection token can be used inside the component

@Component({
  selector: 'my-app',
  template: ` 
  <ul>
    <li>reuseService: {{reuseService.name}}</li>
  </ul>
  ` 
})
export class AppComponent  { 
  constructor(@Inject(REUSE) public reuseService: ReuseService ){}
}

Use the service with different settings

Now we get to the point were we want to be albe to use the service multiple times with a different kind of configuration. This can be useful if you want to trigger different endpoints that return the same object format for example.

First some unique tokens will be created.

export const REUSE_1  = new InjectionToken<ReuseService>('ReuseService1');
export const REUSE_2  = new InjectionToken<ReuseService>('ReuseService2');
export const REUSE_3  = new InjectionToken<ReuseService>('ReuseService3');

These tokens will be used to define our services. In the example bellow we instantiate the service 4 times, each service will have its own instance of the service. If we add state to the services, they will not be shared amongst each other. They live on their own.


@NgModule({
  // imports, declarations, ....
  providers: [
    {
      provide: ReuseService,
      useFactory: reuseFactory("reuse service")
    },
    {
      provide: REUSE_1,
      useFactory: reuseFactory("reuse 1")
    },
    {
      provide: REUSE_2,
      useFactory: reuseFactory("reuse 2")
    },
    {
      provide: REUSE_3,
      useFactory: reuseFactory("reuse 3")
    }
  ]
})
export class AppModule {}

Now the different tokens can be used inside the component

@Component({
  selector: 'my-app',
  template: ` 
  <ul>
    <li>reuseService: {{reuseService.name}}</li>
    <li>reuseService 1: {{reuseService1.name}}</li>
    <li>reuseService 2: {{reuseService2.name}}</li>
    <li>reuseService 3: {{reuseService3.name}}</li>
  </ul>
  ` 
})
export class AppComponent  { 
  constructor(public reuseService: ReuseService,
              @Inject(REUSE_1) public reuseService1: ReuseService,
              @Inject(REUSE_2) public reuseService2: ReuseService,
              @Inject(REUSE_3) public reuseService3: ReuseService, ){}
}

How to name you're interface

Bo Vandersteene — Fri, 11 Oct 2019 08:51:44 +0000

What's you're naming convention on implementing interfaces

You can do it on different ways:

example 1

interface Person { /**define you're method**/}

class PersonImpl implements Person { /**define you're method**/}

example 2

interface IPerson { /**define you're method**/}

class Person implements IPerson { /**define you're method**/}

example 3

interface IPerson { /**define you're method**/}

class PersonImpl implements IPerson { /**define you're method**/}

this list of examples can be extended, feel free to share you're opinion

When a service got destroyed in angular

Bo Vandersteene — Fri, 30 Aug 2019 14:18:27 +0000

Cover Photo by Asa Rodger on Unsplash

If we read the OnDestroy lifecycle hook api description Angular OnDestroy we can use it on services.
But more than this information, we cannot find on it. If we look on the lifecycle hook page. Nothing is explained there, so time to try a few things out.

How we use services?

First we will dig into the usage of services. Services can be provided on different ways to the applications:

On root level

The service is available for everyone, every module can use this root service. It is provided as a singleton, so it lives only ones, and every action on this service, every observable is shared through the whole application.

How can define it on 2 ways. With the providedIn, then you don't provide it in your module

@Injectable({ providedIn: 'root'})
export class RootService { ... }

sidenote on providedIn:

You can also use provideIn: module, but this is still in experimental phase, so be carefull, providedIn: 'root' is good integrated

Or Inject it on the root module

@Injectable()
export class RootService { ... }

@NgModule({
    providers: [ RootService ],
})
export class AppModule{}

On module level

We can also create our services on module level, these services are private and dedicated to that specific module. There logic is shared just inside that module

@Injectable()
export class ModuleService { ... }

@NgModule({
    providers: [ ModuleService ],
})
export class MyCustomModule{}

On component level

These services are injected at component level, so they are only living once the component is alive

// providedIn
@Injectable()
export class Componentervice { ... }

@Component({
    selector: 'my-component',
  template: '...',
    providers: [ Componentervice ],
})
export class MyComponent{}

The lifecycle of a service.

First we are interested when a service is created. We can add a simple test for it. Just create some code like below:

export class MyService {
    constructor(){
        console.log('constructor initialized')
  }
}

To test this logic we have a few testcases, create services on

Root level
Module level
Lazy loaded module
Component level

Initialise the service

All service are initialised on the first usage.

A side-note on services. It is not enough to provide it, we should actual perform an action on that service to be initialised, so adding it to a providers array, is not a way of initialising that service. We can have a fist usage of the service on different ways, like use it through a component or a factory, ….

So knowing that, the services are all initialised on the first usage, that is one thing that we are sure about.
That means also, that lazy loaded services are only initialised the first time a route is loaded, an providedIn: ‘root’ service is only initialised the first time it will be used, …. .

Let’s look at the outputs, here we see an interesting pattern. As expected the root, module and lazy service providers are only once created. When we recreate the component, it the service is not created again

But the most interesting part is the component provided service: Each time the component is created, the service is also created

Only component providers are created each time a component is created

Destroy the service

Now we do the same thing but we destroy the service with the ngOnDestroy hook.
For some reasons we thick the preserve log checkbox in google, so we can track the history of our logging even when we leave the page.

Again the testing code will be similar for each service

@Injectable()
export class MyService implements OnDestroy {
  name = 'xxx service';

  constructor(private counterService: CounterService) { 
    console.log('Construct the xxx service')
  }  

  ngOnDestroy() {   
    console.log('Destroy the xxx service')
  }
}

First we look at the component service, as we have the component service each time created, we expect that it destroys when the component get destroys.

If we look at the 3 other services, then we see that these are never destroyed. Even not when we leave the page. You can get it by accident when you leave the page, but you are not ensured about this.

So the conclusion on this ngOnDestroy hook:

Conclusion

You are never sure that a service is destroyed, expect if you provide it on component level
If you provide a service on component level and you refactor your code, then you need to pay attention on this

Be careful when you use this hook on services

Complete tryout is available on stackblitz: