Accéder au contenu principal

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"
  ]
}

Copying Assets​

Static assets in the public directory are copied to the build output directory by default. If you want to copy additional assets outside of that directory, use the nxCopyAssetsPlugin Vite plugin.

Import the plugin and set it up:

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

import { defineConfig } from 'vite';
import analog from '@analogjs/platform';
import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => ({
  // ...
  plugins: [analog(), nxCopyAssetsPlugin(['*.md'])],
}));