ngx-gcube

Angular libraries for building gCube/D4Science web applications, published to the @ngx-gcube npm scope.

This repository is the umbrella: conventions, publishing setup, and the docs shared by the whole family. The libraries themselves live in one repository each, cloned inside this directory for convenience (and gitignored here — each has its own remote and its own history).

Package	Repository	What it does
@ngx-gcube/iam	ngx-gcube-iam	Keycloak authentication + gCube context/VRE management: login, token refresh, context token exchange, route guard, HTTP interceptor
@ngx-gcube/storagehub	ngx-gcube-storagehub	StorageHub REST client (@ngx-gcube/storagehub) and base widgets (@ngx-gcube/storagehub/widgets, a secondary entry point)
@ngx-gcube/dynamic-viewer	ngx-gcube-dynamic-viewer	Domain-agnostic, metadata-driven UI framework (view registry, generic Table/List/Tree/Cards/Detail viewers, navigation stack) — extraction from is-gui in progress, no stable API yet

Documentation

Start here if npm packaging is new to you — docs/ covers the concepts, credentials, releasing, starting a new library, and consuming one in an app, with the traps that cost us time called out explicitly.

Naming

gCube is the software, D4Science is the infrastructure. These libraries work with the former, so they are gcube-branded. (Two repos elsewhere — d4science-iam-client, d4science-python-library — suggest otherwise; that's an externally-authored convention copied once by mistake, not a house standard. Don't follow it.)

The brand lives in the npm scope, once, so package names stay functional: @ngx-gcube/iam, not ngx-gcube-iam-lib. Git repositories, which have no scopes, spell it out: ngx-gcube-iam.

Using a library in an app

Map the scope once, in the consuming app's .npmrc — no token needed to read, the registry is public:

@ngx-gcube:registry=https://code-repo.d4science.org/api/packages/gCubeSystem/npm/

Then depend on it normally:

"dependencies": {
  "@ngx-gcube/iam": "^0.4.0"
}

Each library's own README covers its API and setup.

The registry

Packages are hosted in Gitea's built-in npm registry, under the gCubeSystem owner:

https://code-repo.d4science.org/api/packages/gCubeSystem/npm/

Two things about that URL that trip people up:

• It belongs to an owner, not a repository. There is no "npm repo" to create — the registry exists because the org does. A published package can be linked to a repository for display, but doesn't need one.
• The scope and the owner differ on purpose. Scope @ngx-gcube, owner gCubeSystem. The packages are named for the library family; they're hosted in the existing org rather than a dedicated one (decision: Luca, 2026-08-10) because that's where D4Science code lives.

Publishing

Reading is public; publishing needs a Gitea access token with package: Read and Write, in your personal ~/.npmrc — never in a repository:

//code-repo.d4science.org/api/packages/gCubeSystem/npm/:_authToken=<token>

Then, from a library's repo:

# 1. bump projects/<lib>/package.json version + add a CHANGELOG.md entry
ng build <lib>              # 2. compile -> dist/<lib>/
npm publish ./dist/<lib>    # 3. publish
git tag vX.Y.Z && git push --tags   # 4. mark it

You publish dist/<lib>, not the repository. An Angular library must be compiled to Angular Package Format (FESM bundles + .d.ts); the TypeScript source isn't consumable. ng build writes a generated package.json into dist/ — which is why each library's projects/<lib>/package.json carries a publishConfig.registry: ng-packagr copies it into the build output, so a package can never accidentally land on public npmjs.org.

npm picks the registry in this order: --registry flag → publishConfig → scope mapping in .npmrc → npmjs.org. Credentials are then looked up in ~/.npmrc by matching the chosen registry URL.

Versions are immutable. Republishing an existing version fails even if the contents changed — every publish needs a bump. Gitea does let you delete a version from the packages UI, unlike npmjs; use that only to undo a mistake made moments ago, never as routine — anyone who already installed ends up with a lockfile pointing at a tarball that no longer exists.

Adding a new library

1. Create gCubeSystem/ngx-gcube-<name> on Gitea.
2. Scaffold an Angular workspace with a single library project in projects/<name>/. The repo name already carries ngx-gcube, so the project directory doesn't repeat it.
3. Name the package @ngx-gcube/<name> and add publishConfig.registry.
4. Copy .npmrc (scope mapping) from ngx-gcube-iam.
5. Clone it inside this directory — .gitignore excludes every nested project directory, so it stays untracked automatically.

ngx-gcube-iam is the reference implementation for all of the above.

Why one repo per library

House convention (gCubeSystem is ~400 repos, one per artifact), plus independent release cadences and unambiguous tags. The cost is duplicated workspace boilerplate per repo, and cross-library work needing a publish before a sibling can consume it — accepted deliberately.