Skip to main content

Migrating an Angular app to Analog

An existing Angular Single Page Application can be configured to use Analog using a schematic/generator for Angular CLI or Nx workspaces.

Analog is compatible with Angular v15 and above.

Using a Schematic/Generator​

First, install the @analogjs/platform package:

npm install @analogjs/platform --save-dev

Next, run the command to set up the Vite config, update the build/serve targets in the project configuration, move necessary files, and optionally set up Vitest for unit testing.

npx ng generate @analogjs/platform:init --project [your-project-name]

For Nx projects:

npx nx generate @analogjs/platform:init --project [your-project-name]

Updating Global Styles and Scripts​

If you have any global scripts or styles configured in the angular.json, reference them inside the head tag in the index.html.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My Analog app</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
    <link rel="stylesheet" href="/src/styles.css" />
  </head>
  <body>
    <app-root></app-root>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Setting Up Environments​

In an Angular application, fileReplacements are configured in the angular.json for different environments.

Using Environment Variables​

In Analog, you can setup and use environment variables. This is the recommended approach.

Add a .env file to the root of your application, and prefix any public environment variables with VITE_. Do not check this file into your source code repository.

VITE_MY_API_KEY=development-key

# Only available in the server build
MY_SERVER_API_KEY=development-server-key

Import and use the environment variable in your code.

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';

@Injectable({
  providedIn: 'root',
})
export class AuthService {
  private readonly apiKey = import.meta.env['VITE_MY_API_KEY'];

  constructor(private http: HttpClient) {}
}

When deploying, set up your environment variables to their production equivalents.

VITE_MY_API_KEY=production-key

# Only available in the server build
MY_SERVER_API_KEY=production-server-key

Read here for about more information on environment variables.

Using File Replacements​

You can also use the replaceFiles() plugin from Nx to replace files during your build.

Import the plugin and set it up:

/// <reference types="vitest" />

import { defineConfig } from 'vite';
import analog from '@analogjs/platform';
import { replaceFiles } from '@nx/vite/plugins/rollup-replace-files.plugin';

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => ({
  build: {
    target: ['es2020'],
  },
  resolve: {
    mainFields: ['module'],
  },
  plugins: [
    analog(),
    mode === 'production' &&
      replaceFiles([
        {
          replace: 'src/environments/environment.ts',
          with: 'src/environments/environment.prod.ts',
        },
      ]),
  ],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['src/test-setup.ts'],
    include: ['**/*.spec.ts'],
    reporters: ['default'],
  },
  define: {
    'import.meta.vitest': mode !== 'production',
  },
}));

Add the environment files to files array in the tsconfig.app.json may also be necessary.

{
  "extends": "./tsconfig.json",
  // other config
  "files": [
    "src/main.ts",
    "src/main.server.ts",
    "src/environments/environment.prod.ts"
  ]
}