@ojiepermana/angular

This project targets Angular 22 as the minimum supported major for published consumers.

Package manager

Install dependencies from the workspace root with Bun:

bun install

Consumer installation

Install the published package into a consumer Angular workspace with Angular CLI so the required peer dependencies are added to the app's package.json and installed in the same flow:

In the consumer snippets below, @your-scope/angular means the package name your workspace actually installs. Replace it consistently with the published target you use, for example @ojiepermana/angular, @edsis/angular, or another branded alias such as @etos/angular.

ng add @your-scope/angular

The library requires Tailwind CSS ^4.3.0. If the consumer workspace does not already have a compatible Tailwind v4 installation, ng add will add it from the published peerDependencies.

The published package treats Angular >=22.0.0 as the supported peer floor, so consumer workspaces can stay on Angular 22 or move forward to newer majors without having the library artificially pinned to 22.x only.

When updating the library later, use Angular CLI as well:

ng update @your-scope/angular

The package ships ng-add and ng-update metadata so Angular and RxJS companions stay aligned with the supported versions of the library.

If you install the package with npm install, bun add, pnpm add, or yarn add directly, peer dependency installation falls back to the package manager's own behavior. In that flow, install Tailwind manually as well:

bun add @your-scope/angular tailwindcss@^4.3.0

Consumer app styles should import the library theme, Tailwind, and the Tailwind bridge in this order:

@import '@your-scope/angular/theme/styles';
@import 'tailwindcss';
@import '@your-scope/angular/theme/tailwind/theme.css';

Theme entrypoint

The shared theme runtime ships through @your-scope/angular/theme, with granular deep-import surfaces available at @your-scope/angular/theme/services, @your-scope/angular/theme/provider, and @your-scope/angular/theme/token. The CSS assets stay available through @your-scope/angular/theme/styles and @your-scope/angular/theme/tailwind/theme.css.

import { provideMaterialTheme, withMaterialDefaults } from '@your-scope/angular/theme';

@import '@your-scope/angular/theme/styles';
@import 'tailwindcss';
@import '@your-scope/angular/theme/tailwind/theme.css';

For contributors working in this repository, the theme entrypoint source is split into runtime APIs under projects/angular/theme/services, projects/angular/theme/provider, projects/angular/theme/token, and stylesheet assets under projects/angular/theme/css. The stylesheet sources are grouped into foundation/, variants/, and integrations/. Local entrypoint notes live in projects/angular/theme/README.md.

To run the theme-only regression suite from the workspace root, use:

bun run test:theme

Breaking change migration

Granular secondary entrypoints are now the required component and navigation surface. If your app previously imported from the removed @your-scope/angular/component or @your-scope/angular/navigation barrels, migrate in this order:

1. Confirm the package root you install in the consumer app. Keep that same root in every ng add, ng update, stylesheet import, and TypeScript import.
2. Replace broad barrel imports such as @your-scope/angular/component with the smallest matching subpath, for example @your-scope/angular/component/button or @your-scope/angular/component/dropdown-menu.
3. Replace removed navigation imports such as @your-scope/angular/navigation with the matching navigation subpath, for example @your-scope/angular/navigation/sidebar, @your-scope/angular/navigation/topbar, @your-scope/angular/navigation/service, or @your-scope/angular/navigation/types.
4. Update any internal helper imports to their new granular subpaths as well, including utilities such as @your-scope/angular/component/utils.
5. Update schematic commands in the same way. The package name before the colon must match the installed target.

Example migration:

import { ButtonComponent } from '@your-scope/angular/component/button';
import { DropdownMenuComponent } from '@your-scope/angular/component/dropdown-menu';
import { SidebarComponent } from '@your-scope/angular/navigation/sidebar';
import { NavigationService } from '@your-scope/angular/navigation/service';
import { UiNavIconComponent } from '@your-scope/angular/navigation/icon';

Granular imports for production builds

Prefer the smallest subpath that matches the primitives you actually use, especially in Native Federation or other shared-chunk builds. Every component now ships only through its matching granular subpath, for example @your-scope/angular/component/date-picker, @your-scope/angular/component/dropdown-menu, and @your-scope/angular/component/tooltip.

import { AvatarComponent, AvatarFallbackComponent, AvatarImageComponent } from '@your-scope/angular/component/avatar';
import { ButtonComponent } from '@your-scope/angular/component/button';
import { PopoverContentDirective, PopoverTriggerDirective } from '@your-scope/angular/component/popover';
import { cn } from '@your-scope/angular/component/utils';
import { UiNavIconComponent } from '@your-scope/angular/navigation/icon';

@your-scope/angular/component and @your-scope/angular/navigation aggregate barrels have been removed. Consumers should use granular @your-scope/angular/component/<slug> and @your-scope/angular/navigation/<part> imports.

Navigation now follows the same granular pattern: @your-scope/angular/navigation/types, @your-scope/angular/navigation/service, @your-scope/angular/navigation/sidebar, @your-scope/angular/navigation/topbar, @your-scope/angular/navigation/item, @your-scope/angular/navigation/icon, and @your-scope/angular/navigation/demo-data.

The same subpaths are preserved for branded packages. For example, a consumer built from the EDSIS release uses:

import { ButtonComponent } from '@edsis/angular/component/button';
import { cn } from '@edsis/angular/component/utils';
import { UiNavIconComponent } from '@edsis/angular/navigation/icon';

To verify the generated package still publishes smaller entrypoints after a build, run:

bun run build
bun run report:entrypoints -- --check

The size report validates that every granular component and navigation entrypoint resolves to its own module and that the removed ./component and ./navigation parent barrels do not return in the published exports.

Navigation primitives

The navigation library now publishes only granular child entrypoints, so each part can be consumed independently.

import { SidebarComponent } from '@your-scope/angular/navigation/sidebar';
import { TopbarComponent } from '@your-scope/angular/navigation/topbar';
import { NavigationService } from '@your-scope/angular/navigation/service';
import type { NavigationItem, SidebarVariant } from '@your-scope/angular/navigation/types';
import { UiNavIconComponent } from '@your-scope/angular/navigation/icon';

The vertical navigation selector is now sidebar and the projected sidebar slots use sidebar-header and sidebar-footer.

<sidebar [ariaLabel]="'Primary'" [variant]="'default'">
  <div sidebar-header>Brand</div>
  <div sidebar-footer>Footer actions</div>
</sidebar>

Register items through NavigationService.registerItems(...), or pass them directly with the items input when composing a local navigation tree.

SDK generator in a consumer workspace

After @ojiepermana/angular is installed, a consumer workspace can scaffold an SDK config file under config/sdk.config.json and generate an Angular SDK directly from the published schematics:

ng generate @your-scope/angular:sdk-init
# edit config/sdk.config.json
ng generate @your-scope/angular:sdk

The main consumer flow is: create config/sdk.config.json, adjust the OpenAPI input and output target, then run the SDK generator.

If you want short script aliases in the consumer app's package.json, add:

{
  "scripts": {
    "gen:sdk:init": "ng generate @your-scope/angular:sdk-init",
    "gen:sdk": "ng generate @your-scope/angular:sdk"
  }
}

Consumers do not need a gen:sdk:build step because the npm package already ships the compiled schematic runtime.

Common follow-up options:

ng generate @your-scope/angular:sdk-init --path=config/my-sdk.config.json
ng generate @your-scope/angular:sdk --config=config/my-sdk.config.json --dry-run

Code scaffolding

Angular CLI includes powerful code scaffolding tools. To generate a new component, run:

bun run ng generate component component-name

For a complete list of available schematics (such as components, directives, or pipes), run:

bun run ng --help

Building

To build the library, run:

bun run build

This command will compile your project, and the build artifacts will be placed in the dist/ directory.

To inspect the generated entrypoint sizes after a build, run:

bun run report:entrypoints

Publishing the Library

Publish the scoped package to the public npm registry from the workspace root.

First, log in to npm:

npm login

Then run:

bun run publish

By default, this command publishes every configured release target from config/release.config.json.

Release targets are configured in config/release.config.json. Each entry can override the published package name plus repository, homepage, and bugs metadata so npm shows the correct package identity.

To publish the edsis target from that config, run:

bun run publish --edsis

To publish every configured release target in sequence, run:

bun run publish -all

bun run publish and bun run publish -all are equivalent.

That flow rebuilds dist/angular for each configured target, rewrites published package references, applies the target-specific npm metadata, smoke-tests the tarball, then publishes it to npm.

EDSIS Verification Flow

To validate the EDSIS package locally without publishing, use:

bun run build -- --package @edsis/angular --repository-url git+https://github.com/edsis/angular.git --homepage https://github.com/edsis/angular#readme --bugs-url https://github.com/edsis/angular/issues
bun run smoke:pack -- --package @edsis/angular

Consumer installation for the published EDSIS package is:

ng add @edsis/angular
bun add @edsis/angular

If you use npm, pnpm, or yarn, install the package with your package manager after ng add finishes.

Running unit tests

To execute unit tests with the Karma test runner, use the following command:

bun run test

Running end-to-end tests

For end-to-end (e2e) testing, run:

bun run ng e2e

Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.

Additional Resources

For more information on using the Angular CLI, including detailed command references, visit the Angular CLI Overview and Command Reference page.