Electrode Native API Generator

Common errors

• cuid2 build error

  cause A transitive dependency `cuid2` encountered build-time issues, potentially due to incompatible tooling or environment configurations.
  fix Update `ern-api-gen` to version `0.53.7` or higher, which contains a fix for this specific build error. Ensure your `yarn.lock` or `package-lock.json` is updated and dependencies are reinstalled.

• Error: Cannot find module '@babel/runtime/helpers/esm/defineProperty' or similar ESM/CJS resolution errors.

  cause Metro bundler, used by React Native, might fail to resolve modules with `.mjs` extensions or encounter other ESM/CommonJS interoperability issues.
  fix Ensure `ern-api-gen` is updated to a version that addresses Metro configuration for `.mjs` (e.g., `0.51.2` or newer). Verify your project's Metro configuration supports `.mjs` files.

• Error: Gradle project 'app' not found

  cause This error typically indicates that the Electrode Native CLI, or `ern-api-gen`'s underlying Android generation, cannot properly locate or configure the Android project, often due to an incompatible Android Gradle Plugin (AGP) version.
  fix Upgrade `ern-api-gen` to a version that officially supports your current Android Gradle Plugin (AGP) version (e.g., `0.53.2` for AGP 8). Confirm your Electrode Native setup and Gradle configuration are consistent with recommended versions.

Warnings

• breaking The package underwent a significant rename from `ern-message-gen` to `ern-api-gen` on August 9, 2017. Any existing projects or scripts referencing the older package name will require updates to function correctly with newer versions.
  Fix: Update all package references and usage in `package.json` and code from `ern-message-gen` to `ern-api-gen`.
• breaking Early versions of the generator saw major internal architectural shifts, including a conversion from Java (initial codebase) to JavaScript (Apr 2017), and subsequently a full conversion to TypeScript (Apr-May 2018/2019). These changes mean that internal APIs are highly unstable across major historical versions, making direct programmatic integration with internal components unreliable.
  Fix: Avoid direct reliance on undocumented or internal APIs of `ern-api-gen`. When upgrading, always consult the official Electrode Native documentation and changelogs for any breaking changes related to its CLI tools.
• gotcha Ensuring compatibility with your specific React Native and Android Gradle Plugin (AGP) versions is crucial. `ern-api-gen` is frequently updated to support newer React Native versions (e.g., 0.77, 0.81) and AGP versions (e.g., AGP 8). Using an `ern-api-gen` version that predates support for your project's React Native or AGP version can lead to build failures and unexpected runtime issues.
  Fix: Regularly update `ern-api-gen` to the latest stable version compatible with your Electrode Native and React Native ecosystem. Refer to Electrode Native's official release notes and compatibility matrices.
• gotcha Specific dependency resolution problems, such as 'cuid2 build error' or issues related to `path-loader` resolutions, have been identified and patched in certain recent versions. These often manifest as cryptic build errors due to conflicts in transitive dependencies or incorrect module resolution.
  Fix: Upgrade `ern-api-gen` to the latest patch release (e.g., `0.53.7` or newer) which includes fixes for known dependency issues. Consider cleaning your `node_modules` and regenerating `package-lock.json` or `yarn.lock` files if issues persist.

Install

• npm install ern-api-gen npm
• yarn add ern-api-gen yarn
• pnpm add ern-api-gen pnpm

Imports

• DefaultCodegen

  import { DefaultCodegen } from 'ern-api-gen/dist/src/DefaultCodegen'

  This package is primarily a CLI tool. Direct programmatic imports are typically only for advanced scenarios like extending or customizing the generator itself. `DefaultCodegen` is a base class for the internal code generators, adapted from Swagger, not a common API for end-users.
• ErnES6ApiCodegen

  import { ErnES6ApiCodegen } from 'ern-api-gen/dist/src/languages/ErnES6ApiCodegen'

  Another example of an internal class for those looking to extend or customize the ES6 API generation logic. This is not for consuming generated APIs, but for modifying the generator's behavior.
• ErnAndroidApiCodegen

  import { ErnAndroidApiCodegen } from 'ern-api-gen/dist/src/languages/ErnAndroidApiCodegen'

  Similar to `ErnES6ApiCodegen`, this represents an internal class for advanced customization of the Android API generation. It is not intended for standard application development, where the generated API client would be imported from its own package.

Quickstart

Demonstrates the canonical command-line interface usage of `ern-api-gen` via the Electrode Native CLI to generate a new API project from a Swagger/OpenAPI schema.

/* 
  The primary way to use ern-api-gen is via the Electrode Native CLI.
  First, ensure you have the Electrode Native CLI installed globally:
  npm install -g ern-cli

  Then, in your terminal, use the `ern create-api` command.
  Replace `path/to/your/swagger.json` with your actual OpenAPI/Swagger schema file path.
  Replace `MyAwesomeApi` with your desired API name.
*/

const SCHEMA_FILE_PATH = 'path/to/your/swagger.json'; // e.g., './api-spec/my-service.json'
const API_NAME = 'MyAwesomeApi'; // This will be the name of your generated API package

console.log(`
To generate a new Electrode Native API project named '${API_NAME}'
from your Swagger/OpenAPI schema located at '${SCHEMA_FILE_PATH}',
run the following command in your terminal:
`);

console.log(`ern create-api ${API_NAME} --schemaPath ${SCHEMA_FILE_PATH}`);

console.log(`
This will create a new directory named '${API_NAME}' containing the generated
JavaScript (React Native), Android, and iOS client code, along with models.
`);

console.log(`
After generation, you can publish the created API project to npm.
For more details, refer to the official Electrode Native documentation:
https://native.electrode.io/cli-commands/create-api
`);