@gravitee/gamma-modules-sdk
Shared contract between the Gamma host (gamma-console) and federated remote modules. Provides types, interfaces, and runtime stubs that are replaced at runtime by the host's real implementation via Module Federation.
Install
yarn add @gravitee/gamma-modules-sdk
Branching
main is the default branch and the release line. Branch feature work from main. Merges to main publish a stable version to npm via semantic-release.
Architecture
The SDK publishes four entry points:
| Entry point | Contents | Used by |
|---|---|---|
@gravitee/gamma-modules-sdk | Types + runtime stubs | Remotes (and host barrel) |
@gravitee/gamma-modules-sdk/types | Interfaces only (no runtime) | Host implementation |
@gravitee/gamma-modules-sdk/routing | Module route helpers | Remotes |
@gravitee/gamma-modules-sdk/mock | OpenAPI mock middleware | Module dev servers |
Remote modules compile and bundle against the stubs. At runtime, the host provides its real implementation as a Module Federation singleton (additionalShared), replacing the stubs transparently.
Remote usage
import { useHasPermission, PermissionGate } from '@gravitee/gamma-modules-sdk';
function MyPage() {
const canEdit = useHasPermission({ anyOf: ['environment-api-u'] });
return (
<PermissionGate anyOf={['environment-api-r']}>
<p>Protected content</p>
</PermissionGate>
);
}
Host implementation
The host imports interfaces from the /types sub-path (which is not captured by the rspack alias or tsconfig path override) to enforce compile-time contract compliance:
import type { IPermissionService, PermissionScope } from '@gravitee/gamma-modules-sdk/types';
export class PermissionService implements IPermissionService {
load(scope: PermissionScope, permissions: string[]): void {
/* ... */
}
// TypeScript will error if any method is missing or has wrong signature
}
Module Federation config
Both host and remotes declare the SDK as a shared singleton:
additionalShared: [
['@gravitee/gamma-modules-sdk', { singleton: true, requiredVersion: false, strictVersion: false }],
],
The host's rspack config uses an exact-match alias so that sub-path imports (/types) resolve from node_modules:
resolve: {
alias: {
'@gravitee/gamma-modules-sdk$': gammaModulesSdkEntry, // note the $ for exact match
},
},
Exports
Mock middleware (/mock)
OpenAPI-based mock middleware for standalone dev mode. Reads OpenAPI specs and serves mock responses from fixture files, so modules can run without a backend.
import { createOpenApiMockMiddleware } from '@gravitee/gamma-modules-sdk/mock';
// In rsbuild.config.ts setupMiddlewares:
createOpenApiMockMiddleware({
moduleId: 'aim',
specs: [join(__dirname, 'src/main/resources/openapi/openapi-catalog.yaml')],
fixturesDir: join(__dirname, 'src/main/resources/catalog-fixtures'),
});
Handles GET list (pagination, ?q= search), GET by ID, sub-resource filtering, POST, PUT, DELETE, and the /gamma/ui/bootstrap endpoint.
Fixture files are named after the last path segment in the spec (e.g. models.json, mcp-servers.json).
Setting up standalone dev mode for a new module
- Add
public/constants.jsonwith{ "gammaBaseURL": "/gamma" } - Write your OpenAPI spec (or copy from an existing module)
- Add fixture JSON files matching your spec paths (e.g.
models.jsonfor/catalog/models) - In
rsbuild.config.ts:
import { createOpenApiMockMiddleware } from '@gravitee/gamma-modules-sdk/mock';
export default defineConfig(() => ({
dev: {
setupMiddlewares: [
(middlewares) => {
middlewares.unshift(
createOpenApiMockMiddleware({
moduleId: 'your-module',
specs: [join(__dirname, 'path/to/openapi.yaml')],
fixturesDir: join(__dirname, 'path/to/fixtures'),
}),
);
return middlewares;
},
],
},
}));
- Run
yarn serveand open http://localhost:3002
Permissions domain
Types: PermissionScope, PermissionCheck, UserRole, PermissionGateProps, UseHasPermissionOptions
Interfaces (from /types): IPermissionService, UseHasPermissionFn, PermissionGateFn, NormalizeCrudMapRecordFn, NormalizeOrgPermissionsFn
Stubs: PermissionService, permissionService, useHasPermission, PermissionGate, normalizeCrudMapRecord, normalizeOrganizationPermissionsFromRoles
License domain
Types: License
Interfaces (from /types): ILicenseService, UseHasFeatureFn, UseHasPackFn
Stubs: LicenseService, licenseService, useHasFeature, useHasPack
Environment domain
Types: Environment
Interfaces (from /types): IEnvironmentService, UseEnvironmentFn
Stubs: EnvironmentService, environmentService, useEnvironment
Routing (/routing)
Helpers for federated modules mounted under /environments/:envHrid/:moduleId/<routePath>: ModuleRouteConfig, useModuleRouting, useToHref, isRouteKey.
useModuleRouting(config) gives each route key one destination, used by both links and clicks:
pathForKey(key): the router path, fornavigate()and<Link to>.hrefForKey(key): the same path under the router's base path, for an<a href>that can be opened in a new tab.navigateToKey(key):navigate(pathForKey(key)).
All three throw on a key missing from config.routes. hrefForKey runs while the nav is built, so an unknown key fails the render, not only the click: guard nav items that are not routes (e.g. external links) with isRouteKey.
A module that resolves its active item itself can still use useModuleRouting for these, and ignore activeNavKey. A module whose clicks go through a guard (e.g. an unsaved-changes prompt) should pass pathForKey(key) to its own guarded navigate instead of using navigateToKey, which calls React Router's navigate directly.
useToHref() returns a function that prefixes the router's base path to an absolute router path, for an <a href> or Graphene's breadcrumb toHref option. It needs no route config. The path must start with /, and a relative path throws: Graphene's option allows a relative to, but the hook cannot know whether navigate resolved it against the route or the URL, so give crumbs an absolute to (e.g. from pathForKey).
Graphene types nav item keys as string. isRouteKey narrows them to the module's route keys, so no cast is needed:
const { activeNavKey, hrefForKey, navigateToKey } = useModuleRouting(ROUTE_CONFIG);
const toHref = useToHref();
const groups = NAV_GROUPS.map((group) => ({
...group,
items: group.items.map((item) =>
isRouteKey(item.key, ROUTE_CONFIG.routeKeys) ? { ...item, href: hrefForKey(item.key) } : item,
),
}));
<SidebarNavigation
groups={groups}
activeItemKey={activeNavKey}
onItemSelect={(key) => isRouteKey(key, ROUTE_CONFIG.routeKeys) && navigateToKey(key)}
/>;
buildLinearBreadcrumbs(navigate, segments, { toHref });
Development
Prerequisites
- Node.js 24+ (see
.nvmrc) - Yarn 4 (enabled via Corepack)
A full local Gamma stack is in docker/README.md. For Kind instead, use the gck Gamma context.
Commands
yarn install # Install dependencies
yarn build # Typecheck + Vite build
yarn test # Vitest
yarn lint # ESLint
yarn lint:fix:all # ESLint --fix, Prettier write
yarn format:check # Prettier check
yarn typecheck # TypeScript only
For a full local check before a pull request, yarn lint:fix:all runs ESLint with fixes and Prettier to format the tree.
Local development with gamma-console
To iterate on SDK changes alongside the host or a remote without publishing:
# In this repo
yarn build
yarn link
# In gravitee-api-management
yarn link @gravitee/gamma-modules-sdk
Contributing
- Branch from
main, make changes, and open a pull request - Use Conventional Commits for commit messages
- On feature branches, CI runs lint, typecheck, build, test, and a branch-scoped npm prerelease
- Merges to
mainpublish a stable version on npm via semantic-release
Releases
Releases are automated on main via semantic-release.
The version is derived from conventional commit messages:
fix:-> patchfeat:-> minorfeat!:orBREAKING CHANGE:-> major