ZITADEL Node.js (Import Compatibility Fork)

Note: This is a fork of the original ZITADEL Node.js SDK that enables ES import syntax in environments that require it, including NestJS and other CommonJS-based applications.

This library contains the compiled and generated gRPC service clients for the ZITADEL API, packaged to work with import syntax in TypeScript environments.

Fork Features

• ✅ ES Import Support: Use import statements in CommonJS environments like NestJS
• ✅ Dual Package: Compatible with both CommonJS and ES Module environments
• ✅ TypeScript Support: Full type definitions and IntelliSense
• ✅ Drop-in Replacement: Same API as the original package

Usage

Installation

npm install @ragnaraven/zitadel-node-dual
# or
pnpm add @ragnaraven/zitadel-node-dual

Quick Start

See the /examples folder for complete usage examples:

• api-example.ts - Basic API usage
• nestjs-service.example.ts - NestJS integration

Original Documentation

For complete documentation, API reference, and additional examples, please refer to the original ZITADEL Node.js SDK repository.

This fork maintains full compatibility with the original API while adding import syntax support for CommonJS environments.

Goals

This fork extends the original goals to include:

• ✅ Support ES import syntax in CommonJS environments
• ✅ Maintain compatibility across module systems

The original package completed these goals:

• ✅ Provide compiled proto clients
• ✅ Manage resources via proto clients
• ✅ Allow authentication of a service account

Development

This fork follows the same development process as the original:

1. Clone this repository
2. Install the dependencies with npm install
3. Install the submodules with git submodule update --init --recursive
4. Generate the gRPC types with npm run build:grpc or npm run build:grpc:windows
5. Build dual packages with npm run build:dual

Windows Development

If you're developing on Windows, use the Windows-specific build command:

npm run build:windows

This uses buf.gen.windows.yaml which includes the Windows-specific .cmd path for protoc-gen-ts_proto. The standard npm run build command may fail on Windows due to cross-platform path resolution issues with the buf generate process.

Windows Commands:

• npm run build:windows - Full build with Windows-compatible gRPC generation
• npm run build:grpc:windows - Just the gRPC generation step for Windows
• npm run build:dual - Just the TypeScript compilation (works cross-platform)

The dual build process creates:

• dist/cjs/ - CommonJS build
• dist/esm/ - ES Module build
• dist/types/ - TypeScript declarations

Testing

Run the test suite:

npm test

Tests cover client creation, API calls, and authentication flows across both CommonJS and ES Module environments.

Contributing

For issues specific to this fork, please open issues in this repository.

For general ZITADEL Node.js SDK issues, please refer to the original repository.