Standalone Component Imports: Angular Fix

You convert a component to standalone, save, and the template fills with red: 'app-avatar' is not a known element. The component exists. It worked yesterday. The only change is the standalone flag, and suddenly Angular can't see a file sitting right next to it.

Standalone components carry no NgModule, so nothing supplies their template dependencies implicitly. Every child component, directive, pipe, and helper module must appear in the component's own imports array. Yesterday AppModule provided AvatarComponent to the whole feature; today nobody provides it to your template. The compiler is right: from its scope, that selector doesn't exist.

Migration multiplies the confusion. Half the codebase still lives in modules while the other half imports directly, and each dependency demands the wiring style its author chose. Router directives, CommonModule structural directives, and third-party UI pieces each fail in their own dialect of the same missing-import error.

This guide untangles it. You'll learn the standalone imports mental model, how it differs from NgModule wiring, which entries router and structural directives need, how to mix both eras safely, and how to migrate feature by feature without breaking half your routes.

The Standalone Imports Mental Model

A standalone component's imports array is the complete list of what its template may use. Child components, attribute directives, structural directives via their modules, and pipes all enter scope exclusively through this array. Nothing is inherited from parents, nothing leaks sideways from siblings, and nothing arrives globally. When the compiler reports an unknown element, it means exactly what it says: within this template's scope, that selector was never registered.

This explicitness replaces the old transitive visibility where importing a module granted its entire export surface to every template in the feature. The new model trades that convenience for precision: templates declare their true dependencies, the bundler drops everything else, and readers see the full dependency list without chasing module files. The cost is repetition: a component used in ten templates appears in ten imports arrays, which feels verbose until you realize each entry is documentation.

Build the verification habit mechanically. For every selector in the template, find its owner and confirm the import entry. Automate the check with lint rules that flag unknown selectors at PR time, and keep a snippet that scaffolds new components with the common imports pre-listed. Developers who map selectors to imports as they type never meet this error; developers who add imports after the fact meet it weekly.

import { Component } from '@angular/core';
import { AvatarComponent } from './avatar.component';
import { BadgeComponent } from './badge.component';

@Component({
  selector: 'app-header',
  standalone: true,
  // Every selector used below must appear here.
  imports: [AvatarComponent, BadgeComponent],
  template: `
    <header>
      <app-avatar user="ana"></app-avatar>
      <app-badge label="pro"></app-badge>
    </header>
  `,
})
export class HeaderComponent {}

NgModule vs Standalone Wiring Compared

NgModule wiring and standalone wiring solve the same scoping problem from opposite ends. A module declares its components once and imports shared dependencies once for all its templates. A standalone component imports its own dependencies once for its own template. Mixed codebases must respect both directions: modules consume standalone components through their imports array, while standalone components consume modules, or other standalone pieces, through theirs.

Two crossings are illegal and produce confusing errors. A non-standalone component can't appear in a standalone imports array; import its owning module instead. A standalone component can't appear in a module's declarations; list it under imports. The error messages name the violation precisely, but developers misread them as missing-dependency errors and add more wrong entries. Read the message literally: it states which crossing you attempted.

Migration strategy follows the dependency leaves inward. Convert leaf components with no children first: their imports arrays are small and verifiable. Then convert features whose children are already standalone. Convert bootstrap and routing last, when providers can move to functional equivalents. Verify each step with a production build, because dev-server tolerance hides wiring gaps that AOT exposes at the worst moment.

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { HeaderComponent } from './header.component';

@NgModule({
  declarations: [],
  // Standalone pieces enter modules through imports.
  imports: [CommonModule, HeaderComponent],
  exports: [HeaderComponent],
})
export class SharedModule {}

// Standalone consumer needs no module at all:
// imports: [HeaderComponent] in the using component.

Router and Structural Directives Need Imports Too

Router directives surprise migrators because routing feels like infrastructure that should just work. It doesn't: routerLink, routerLinkActive, and router-outlet are directives like any other, entering standalone templates only through RouterModule imports. A component that navigated fine under a routing module fails standalone with unknown-property errors on routerLink, while the route configuration itself remains perfectly valid.

Structural directives follow the same rule through CommonModule. A standalone template using ngIf or ngFor without importing CommonModule errors on the directive while custom selectors resolve fine, which sends developers hunting through component imports for a problem in module imports. Memorize the pairing: control flow needs CommonModule, two-way forms need FormsModule, routing needs RouterModule. Each is one import entry beside your components.

Scaffold discipline prevents the whole category. Team snippets for new standalone components should pre-import CommonModule and RouterModule where the feature needs them, leaving developers to add only business components. Review checklists should ask which directives the template uses, not just which components. Directives are invisible in the rendered page but mandatory in the imports array.

import { Component } from '@angular/core';
import { RouterModule } from '@angular/router';
import { AvatarComponent } from './avatar.component';

@Component({
  selector: 'app-nav',
  standalone: true,
  imports: [RouterModule, AvatarComponent],
  template: `
    <nav>
      <a routerLink="/team">Team</a>
      <app-avatar user="ana"></app-avatar>
    </nav>
    <router-outlet></router-outlet>
  `,
})
export class NavComponent {}

Providers Move Too: the importProvidersFrom Bridge

Providers follow a parallel migration path that intersects imports at bootstrap. NgModules contributed providers through their imports; standalone apps contribute them through the providers array in app.config.ts or bootstrapApplication. Deleting a module import during migration removes its provider recipes as well as its directives, which is how a component conversion produces a NullInjectorError two routes away from the edited file.

importProvidersFrom is the sanctioned bridge for half-migrated apps. It pulls an unmigrated module's providers into the standalone bootstrap context without converting the module itself. Use it for third-party modules lacking functional providers, and replace each bridge with a functional equivalent like provideHttpClient() as libraries modernize. Every bridge deserves a comment naming the module and the planned replacement, or bridges become permanent.

Audit deletions against additions during every migration PR. For each removed module import, answer two questions: which directives did it supply, and which providers did it register. Directives move to component imports arrays; providers move to app.config.ts. PRs that answer both explicitly merge safely; PRs that move syntax without tracing semantics break routes. The checklist is short but non-negotiable.

import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideHttpClient } from '@angular/common/http';
import { importProvidersFrom } from '@angular/core';
import { LegacyModule } from './legacy.module';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideHttpClient(),
    // Bridge for modules that haven't migrated yet.
    importProvidersFrom(LegacyModule),
  ],
};

Third-Party Libraries Across Both Eras

Third-party libraries split across both eras, and each demands its own wiring. A standalone UI component imports directly into your imports array. A module-based UI kit imports as a module, granting its exported components to your template. Guessing wrong produces errors about unexpected imports or unknown elements that look like version bugs but are really style mismatches.

The decorator is the ground truth when docs lag. Open the library source or its type definitions and check for standalone: true on the component. Present means direct import; absent means import the owning module. Docs for popular kits usually state the style per version, but transitive dependencies and beta releases often trail behind. Thirty seconds reading the decorator beats thirty minutes fighting the compiler.

Pin and verify library wiring in CI. A production build over a lockfile catches renames, style changes, and dropped exports before they reach main. When upgrading UI kits, grep templates for affected selectors first and update them in the same commit as the version bump. Library imports are contracts with external authors; treat version bumps as renegotiations, not chores. Renegotiate carefully and the integration stays quiet for months.

The Selector Roll Call That Prevents All of This

A systematic pass prevents wiring bugs from surviving to build time. Read the template top to bottom, list every custom selector, directive, and pipe, and map each to its owning file and standalone status. Open the imports array and check off each entry. Unchecked items are future compiler errors; check them now while the template's intent is fresh in mind.

Do this pass at creation time, not review time. The author holds the full context of which pieces the template needs, while reviewers reconstruct it from diffs. A two-minute roll call during writing saves a twenty-minute debugging session later plus the CI cycle in between. Make it part of the definition of done for every standalone component.

Enforce it mechanically where humans slip. Lint rules flag unknown selectors at PR time, real-template specs fail on missing imports, and production builds verify the whole graph. Human discipline starts the habit; automation keeps it alive across team growth and deadline pressure. Components maintained this way import exactly what they use, no more and no less. Roll calls take two minutes and save twenty; make them automatic and the savings compound across every sprint and every new hire.