@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

Stable (from main):

yarn add @gravitee/gamma-modules-sdk

Prerelease while development is integrated in other repos (from alpha):

yarn add @gravitee/gamma-modules-sdk@alpha

Branching

| Branch | Role | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | alpha | Day-to-day development and prerelease versions published to the npm alpha dist-tag. Use this until the SDK is verified with gamma-console and remote modules. | | main | Stable releases. Merge or promote from alpha when you are ready for a real public release. |

In GitHub, set the default branch to alpha while you are in this phase so new pull requests and clones target the integration line by default.

Architecture

The SDK publishes three 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/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

1. Add public/constants.json with { "gammaBaseURL": "/gamma" }
2. Write your OpenAPI spec (or copy from an existing module)
3. Add fixture JSON files matching your spec paths (e.g. models.json for /catalog/models)
4. 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;
      },
    ],
  },
}));

5. Run yarn serve and 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

Development

Prerequisites

• Node.js 24+ (see .nvmrc)
• Yarn 4 (enabled via Corepack)

Commands

yarn install          # Install dependencies
yarn build            # Typecheck + Vite build
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

1. Branch from alpha (or the repository default), make changes, and open a pull request
2. Use Conventional Commits for commit messages
3. On non-main / non-alpha feature branches, CI runs lint, typecheck, build, and (where configured) branch-scoped npm prerelease builds
4. Merges to alpha trigger a prerelease (npm alpha dist-tag) via semantic-release when the pipeline is enabled
5. Merges to main trigger a stable version on npm. Promote to main when integration with the rest of the stack is confirmed

Releases

Releases are automated on main (stable) and alpha (prerelease) via semantic-release. Prerelease versions on alpha are published for consumers to pin with yarn add @gravitee/gamma-modules-sdk@alpha until you are ready to ship from main.

The version is derived from conventional commit messages:

• fix: -> patch
• feat: -> minor
• feat!: or BREAKING CHANGE: -> major

License

Apache 2.0