@norce/admin-chunk

Angular library extracted from commerce-admin. Independently built and published package for parts of the Norce Commerce Admin UI.

PrimeNG (unstyled) for component behavior, custom SCSS with --norce-* design tokens for visuals. See CLAUDE.md for development conventions and component guidelines.

Getting started

git clone [email protected]:NorceTech/admin-chunk.git
cd admin-chunk
npm install
npm run build

Release

One command bumps the version, rebuilds dist/, commits, tags, publishes to npm, and pushes the commit and tag:

npm version patch    # 0.0.6 → 0.0.7
npm version minor    # 0.0.6 → 0.1.0
npm version major    # 0.0.6 → 1.0.0

This is wired through the standard version / postversion lifecycle hooks in package.json. npm version itself refuses to run if the working tree is dirty.

Prerequisites

• Logged in to npm with publish rights to @norce: npm login
• A current 2FA OTP from your authenticator (npm prompts mid-publish)
• On main with a clean working tree

Recovery

If publish fails after the version bump (typical cause: expired OTP, network blip), you have a local commit + tag for an unpublished version. Either retry the publish + push manually, or roll back and start over:

# Retry path
npm publish ./dist --otp=<fresh-otp> && git push --follow-tags

# Roll-back path
git tag -d v<new-version>
git reset --hard HEAD~1

If publish succeeded but push didn't, just git push --follow-tags manually — the tarball is already public on npm.

Updating the host

# In commerce-admin/Storm.Admin.UI
npm install @norce/admin-chunk@<new-version>

API client regeneration

When the backend API changes:

# 1. Refresh openapi-spec.json from a running local Admin.API
#    (defaults to http://localhost:5021/openapi/admin.v1.json)
npm run generate:spec
# 2. Regenerate services and models
npm run generate:api
# 3. Build and verify
npm run build

context-header.interceptor.ts is hand-written and will NOT be overwritten.

Local development with the host

The host (commerce-admin/Storm.Admin.UI) already has preserveSymlinks: true in its angular.json build options, so linking is a one-liner per side:

# Terminal 1 — library
npm run build
cd dist && npm link
cd .. && npm run watch

# Terminal 2 — host (commerce-admin/Storm.Admin.UI)
npm link @norce/admin-chunk
ng serve

To unlink and go back to published:

npm unlink @norce/admin-chunk
npm install @norce/admin-chunk

preserveSymlinks can stay on — it's harmless with a real node_modules install.

Host integration

After npm install @norce/admin-chunk primeng, the host needs 5 changes:

1. Include the global theme stylesheet

File: angular.json — add to the styles array (before src/styles.scss):

"node_modules/@norce/admin-chunk/styles/norce-theme.css"

2. Provide library configuration

File: src/main.ts — call provideNorceAdminChunk({ basePath }) in applicationProviders. This configures the API client and PrimeNG unstyled mode in a single call. The basePath varies by environment; see the host branch for the current implementation.

3. Register the interceptor

File: src/app/core/core.module.ts — add contextHeaderInterceptor to the existing withInterceptors() array. It only processes requests with /admin-api in the URL.

4. Push context from ContextService

File: src/app/core/context.service.ts — inject NorceContextStore, call .update() in setContext() after this.context.isLoaded = true. Maps legacy context fields to NorceContext. See src/lib/core/norce-context.ts for the interface.

5. Wire up routes and navigation

• src/app/app.routing.ts — lazy route: import('@norce/admin-chunk').then(m => m.norceRoutes) under /norce with AuthGuard
• src/app/app.component.ts — add nav entries for Dashboard and Suppliers

The host provides auth, routing, base URL, and context. The library handles everything else.

Caveats

1. API path prefix — generated services build URLs as ${basePath}${path}, where path already starts with /api/.... The host's provideNorceAdminChunk({ basePath }) must therefore be the API root only — /admin-api in dev, <apiUrl>/admin-api in prod. Setting it to /admin-api/api makes every request 404 as /admin-api/api/api/....
2. preserveSymlinks — required with npm link, remove when using the published package.
3. Publish from dist/ — the root package.json has devDependencies that should not be published.