Nestia CLI Tool

Common errors

• Error: Command 'sdk' is not registered.

  cause Attempting to run a Nestia command that is not recognized by the current version or installation.
  fix Ensure `nestia` is installed correctly via `npm install -D nestia` or `yarn add -D nestia`. Verify the command exists in your `package.json` scripts or is called directly via `npx nestia <command>`.

• Error: Configuration file "nestia.config.ts" not found.

  cause Nestia CLI commands, especially `sdk` or `swagger`, require a configuration file, typically `nestia.config.ts`, in the project root.
  fix Create `nestia.config.ts` in your project root. You can generate a basic one with `npx nestia init --project tsconfig.json`.

• TypeError: (0, _nestia_sdk__WEBPACK_IMPORTED_MODULE_0__.is) is not a function

  cause This often indicates an issue with Typia's runtime validation setup, where the `is` function (or similar `typia` functions) is not correctly imported or bundled.
  fix Ensure `typia` is installed (`npm install typia`) and that your `nestia.config.ts` correctly configures Typia. Verify your `tsconfig.json` includes the necessary settings for transformer plugins if applicable.

• TS2307: Cannot find module '@nestia/core' or its corresponding type declarations.

  cause The `@nestia/core` package is not installed or TypeScript cannot locate its type definitions.
  fix Install `@nestia/core` as a dependency: `npm install @nestia/core` or `yarn add @nestia/core`. Ensure your `tsconfig.json` includes `node_modules/@nestia/core` in its `include` or `types` paths, though this is usually handled automatically.

Warnings

• breaking The way Typia validates programmers has changed in v11.0.0. This may require adjustments to existing validation logic or configurations when upgrading.
  Fix: Review Nestia's documentation on Typia integration and update any custom validation setups or configurations (`nestia.config.ts`) accordingly. Look for changes related to `INestiaTransformOptions.typia`.
• breaking In v10.0.1, the SDK generator changed the escape symbol from `$` to `_` for generated client symbols to avoid conflicts. If your client code or generated files relied on the `$` symbol, they will break.
  Fix: Regenerate your client SDKs and update any code that interacts with the generated symbols, replacing `$` with `_` as per the new escaping mechanism. Example: `Api$Users` becomes `Api_Users`.
• breaking Nestia v10.0.0 introduced a 'universal LLM schema' feature. This likely entails changes to how LLM-related schemas are generated or configured within Nestia, potentially breaking existing AI Chatbot integrations.
  Fix: Consult the Nestia documentation on 'AI Chatbot Development' and 'universal LLM schema' for v10 to understand the new configuration and schema generation process. Update `nestia.config.ts` if necessary.
• gotcha Nestia is a code generator. Re-running generation commands (e.g., `nestia sdk`) can overwrite existing files within the target SDK or Swagger output directories. Ensure you manage custom code in separate files or use appropriate configuration options to prevent accidental overwrites.
  Fix: Store custom logic outside of generated files. For instance, extend generated classes/interfaces or import generated types into manually maintained files. Use `.nestia` folder for outputs, and ensure it's in `.gitignore`.
• gotcha Nestia's performance claims (e.g., '20,000x faster than class-validator') are based on specific benchmarks against alternative libraries. While generally faster, actual performance gains in your application depend on your specific workload, data structures, and usage patterns. Proper setup and configuration are critical to realize these benefits.
  Fix: Follow Nestia's official setup guides, especially regarding `typia` integration, to ensure the performance optimizations are correctly applied. Profile your application to confirm the expected performance improvements.

Install

• npm install nestia npm
• yarn add nestia yarn
• pnpm add nestia pnpm

Imports

• main
  wrong:

  const main = require('nestia')

  correct:

  import { main } from 'nestia'

  Primarily for programmatic invocation of the CLI, used in build scripts or custom runners. Not for typical application logic.
• IConfiguration
  wrong:

  import { IConfiguration } from 'nestia'

  correct:

  import type { IConfiguration } from 'nestia'

  Imports the interface for Nestia's configuration object, useful for strongly typing `nestia.config.ts`. Use `import type` for type-only imports.
• ECommand

  import { ECommand } from 'nestia'

  Enum representing available Nestia CLI commands for programmatic command execution.

Quickstart

Demonstrates programmatic initialization of a Nestia project and generation of its SDK and Swagger documentation using the `main` function and `ECommand` enum.

import { ECommand, main } from 'nestia';
import * as path from 'path';
import * as fs from 'fs/promises';

async function setupNestiaProject() {
  const projectDir = path.join(process.cwd(), 'my-nestia-app');
  await fs.mkdir(projectDir, { recursive: true });
  process.chdir(projectDir);

  console.log(`Initializing Nestia project in ${projectDir}...`);
  await main({
    command: ECommand.init,
    input: ['--project', 'tsconfig.json'],
  });
  console.log('Nestia project initialized.');

  console.log('Generating SDK and Swagger...');
  await main({
    command: ECommand.sdk,
    input: ['--config', 'nestia.config.ts'],
  });
  console.log('SDK and Swagger generated successfully.');

  console.log('Now you can explore your generated SDK and Swagger documentation!');
  console.log(`Check out ${path.join(projectDir, 'src/api/index.ts')} for the SDK.`);
}

setupNestiaProject().catch(console.error);