Skip to content

Aurelia App Configuration — Setting Up Your Application Shell

DodaTech Updated 2026-06-28 5 min read

In this tutorial, you will learn about Aurelia App Configuration. We cover key concepts, practical examples, and best practices to help you master this topic.

Aurelia app configuration happens in main.ts where you register plugins, configure global resources, set up logging, and start the application. The configure function is the entry point that bootstraps the entire Aurelia application.

What You'll Learn

You will learn how to configure the Aurelia application, register plugins, create feature modules, set up global resources, and manage environment configuration.

Why It Matters

Proper configuration ensures your application loads efficiently. Registering global resources prevents repetition. Feature modules organize related functionality. Environment configurations manage different deployment targets.

Real-World Use

An enterprise Aurelia app has separate feature modules for admin, reporting, and user management. Each feature registers its own components, converters, and services. The main configuration wires them together and sets environment-specific settings.

flowchart LR
    A[main.ts] --> B[Aurelia.start]
    B --> C[Register plugins]
    B --> D[Register features]
    B --> E[Register global resources]
    B --> F[Set root component]
    F --> G[App Component]
    G --> H[Router]
    G --> I[App Shell Template]

The configure Function

The configure function receives the Aurelia instance and configures plugins, resources, and features.

// src/main.ts
import { Aurelia } from 'aurelia-framework';
import { PLATFORM } from 'aurelia-pal';

export function configure(aurelia) {
  // Standard configuration
  aurelia.use.standardConfiguration();

  // Development logging
  if (process.env.NODE_ENV === 'development') {
    aurelia.use.developmentLogging('debug');
  }

  // Register plugins
  aurelia.use
    .plugin(PLATFORM.moduleName('aurelia-validation'))
    .plugin(PLATFORM.moduleName('aurelia-dialog'))
    .plugin(PLATFORM.moduleName('aurelia-http-client'));

  // Register feature modules
  aurelia.use
    .feature(PLATFORM.moduleName('resources/admin/index'))
    .feature(PLATFORM.moduleName('resources/shared/index'));

  // Start and set root
  aurelia.start().then(() => {
    aurelia.setRoot(PLATFORM.moduleName('app'));
  });
}

Registering Global Resources

Global resources are available in every template without explicit import.

// src/main.ts — Register global resources
export function configure(aurelia) {
  aurelia.use.standardConfiguration();

  // Global custom elements
  aurelia.use.globalResources([
    PLATFORM.moduleName('resources/elements/nav-bar'),
    PLATFORM.moduleName('resources/elements/status-badge'),
    PLATFORM.moduleName('resources/elements/data-table')
  ]);

  // Global value converters
  aurelia.use.globalResources([
    PLATFORM.moduleName('resources/value-converters/currency'),
    PLATFORM.moduleName('resources/value-converters/date-format')
  ]);

  // Global custom attributes
  aurelia.use.globalResources([
    PLATFORM.moduleName('resources/attributes/tooltip'),
    PLATFORM.moduleName('resources/attributes/confirm')
  ]);

  aurelia.start().then(() => aurelia.setRoot(PLATFORM.moduleName('app')));
}

Feature Modules

Features are self-contained modules that register their own resources.

// src/resources/admin/index.ts — Feature registration
import { PLATFORM } from 'aurelia-pal';

export function configure(config) {
  config.globalResources([
    PLATFORM.moduleName('./elements/admin-sidebar'),
    PLATFORM.moduleName('./elements/admin-header'),
    PLATFORM.moduleName('./value-converters/status'),
    PLATFORM.moduleName('./attributes/role-check')
  ]);
}

Environment Configuration

Manage different environments with environment-specific files.

// src/environment.ts
export default {
  development: {
    apiUrl: 'http://localhost:3000/api',
    logging: 'debug',
    enableDebugTools: true
  },
  staging: {
    apiUrl: 'https://staging-api.example.com/api',
    logging: 'info',
    enableDebugTools: false
  },
  production: {
    apiUrl: 'https://api.example.com/api',
    logging: 'warn',
    enableDebugTools: false
  }
}[process.env.NODE_ENV || 'development'];

Feature Configuration Pattern

When a feature needs configuration options, use the configure callback.

// src/resources/notifications/index.ts
export function configure(config, callback) {
  // Configure notification service
  const defaults = {
    position: 'top-right',
    duration: 3000,
    maxVisible: 5
  };

  const options = callback ? callback(defaults) : defaults;

  config.container.registerInstance('notificationConfig', options);
  config.globalResources([
    PLATFORM.moduleName('./notification-service'),
    PLATFORM.moduleName('./notification-toast')
  ]);
}

Plugins with Options

Some Aurelia plugins accept configuration options.

import { Aurelia } from 'aurelia-framework';
import { PLATFORM } from 'aurelia-pal';

export function configure(aurelia) {
  aurelia.use.standardConfiguration();

  aurelia.use.plugin(PLATFORM.moduleName('aurelia-validation'), (config) => {
    // Configure validation
    config.useViewStrategy('aurelia-validation/validation-view-strategy');
    config.addRule('email', /^[^\s@]+@[^\s@]+\.[^\s@]+$/);
  });

  aurelia.use.plugin(PLATFORM.moduleName('aurelia-dialog'), (config) => {
    config.useDefaults();
    config.settings.lock = true;
    config.settings.centerHorizontalOnly = false;
  });

  aurelia.start().then(() => aurelia.setRoot(PLATFORM.moduleName('app')));
}

The Root Component

The root component is the application shell.

// src/app.ts
import { RouterConfiguration, Router } from 'aurelia-router';
import { PLATFORM } from 'aurelia-pal';

export class App {
  router;

  configureRouter(config, router) {
    this.router = router;
    config.title = 'My Aurelia App';
    config.options.pushState = true;
    config.options.root = '/';

    config.map([
      { route: '',          name: 'home',    moduleId: PLATFORM.moduleName('routes/home/home') },
      { route: 'products',  name: 'products', moduleId: PLATFORM.moduleName('routes/products/products') },
      { route: 'about',     name: 'about',   moduleId: PLATFORM.moduleName('routes/about/about') }
    ]);
  }
}

<!-- src/app.html -->
<template>
  <require from="./resources/elements/nav-bar"></require>

  <nav-bar router.bind="router"></nav-bar>

  <main>
    <router-view></router-view>
  </main>

  <footer>
    <p>Built with Aurelia</p>
  </footer>
</template>

Debug Configuration

export function configure(aurelia) {
  aurelia.use.standardConfiguration();

  // Debug configuration
  if (process.env.NODE_ENV === 'development') {
    aurelia.use
      .developmentLogging('debug')
      .plugin(PLATFORM.moduleName('aurelia-testing'));
  }

  // Production optimizations
  if (process.env.NODE_ENV === 'production') {
    aurelia.use
      .plugin(PLATFORM.moduleName('aurelia-loader-nodejs'));
  }

  aurelia.start().then(() => aurelia.setRoot(PLATFORM.moduleName('app')));
}

Common Mistakes

  1. Not using PLATFORM.moduleName for module paths. String paths break in production builds. Always wrap module paths with PLATFORM.moduleName.
  2. Registering the same global resource twice. Duplicate registration causes errors. Check if a resource is already global before registering.
  3. Forgetting to import the configuration function. The configure export must exist in main.ts. Aurelia calls it automatically.
  4. Over-registering global resources. Only register resources used across multiple components. Route-specific resources should be imported locally.
  5. Not handling the async Bootstrap correctly. The aurelia.start() returns a promise. Chain .then() properly or use await.

Practice Questions

  1. What is the purpose of the configure function in main.ts?
  2. How do you register a global resource?
  3. What is a feature module?
  4. How do you configure environment-specific settings?
  5. Challenge: Set up an Aurelia application with three feature modules: core (nav-bar, footer), dashboard (charts, metrics widgets), and admin (user-list, role-manager). Register all components as global resources. Configure different logging levels for development and production.

FAQ

What is `aurelia.use.standardConfiguration()`?

It enables the standard set of Aurelia plugins: router, http-client, templating, and event-aggregator.

Can I lazy-load feature modules?

Yes. Lazy-loading is handled by the bundler. Use PLATFORM.moduleName for all module references.

How do I configure third-party Aurelia plugins?

Pass a callback as the second argument to .plugin(). The callback receives the plugin's configure function.

What happens if `main.ts` is missing?

Aurelia cannot bootstrap. The application fails with a configuration error.

Can I have multiple `setRoot` calls?

No. Call setRoot once. Multiple calls create duplicate application instances.

Mini Project

Create an Aurelia application with a clean configuration. Set up three environment files (dev, staging, prod). Register global resources for nav-bar, footer, data-table, and currency converter. Create feature modules for products and users. Configure the router with four routes. Ensure the app runs in both dev and production modes.

What's Next

Now that configuration is covered, learn about Aurelia Components for building views. Then explore Aurelia Custom Elements for reusable components.

← Previous Aurelia Installation — Setting Up Your Aurelia Project Next → Aurelia Components — Building Views with ViewModels and Templates

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Aurelia