Configuration

Configure @nestbolt/excel with forRoot and forRootAsync -- default file type, CSV settings, storage disks, and more.

ExcelModule is registered globally. Call forRoot() or forRootAsync() once in your root application module and inject ExcelService or DiskManager anywhere in your application.

Static Configuration (forRoot)

Pass an ExcelModuleOptions object directly:

import { Module } from "@nestjs/common";
import { ExcelModule } from "@nestbolt/excel";

@Module({
  imports: [
    ExcelModule.forRoot({
      defaultType: "xlsx",
      tempDirectory: "/tmp/excel",
      csv: {
        delimiter: ",",
        quoteChar: '"',
        lineEnding: "\n",
        useBom: false,
        encoding: "utf-8",
      },
      disks: {
        local: { driver: "local", root: "./storage" },
        s3: {
          driver: "s3",
          bucket: "my-reports",
          region: "us-east-1",
        },
      },
      defaultDisk: "local",
    }),
  ],
})
export class AppModule {}

Calling forRoot() with no arguments uses all defaults -- XLSX output, comma-delimited CSV, and local filesystem storage:

ExcelModule.forRoot();

Async Configuration (forRootAsync)

Use forRootAsync() when your configuration depends on other providers, such as ConfigService:

import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { ExcelModule } from "@nestbolt/excel";

@Module({
  imports: [
    ConfigModule.forRoot(),
    ExcelModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        defaultType: config.get<"xlsx" | "csv">("EXCEL_DEFAULT_TYPE", "xlsx"),
        csv: {
          delimiter: config.get("CSV_DELIMITER", ","),
          useBom: config.get("CSV_USE_BOM", false),
        },
        disks: {
          s3: {
            driver: "s3" as const,
            bucket: config.getOrThrow("S3_BUCKET"),
            region: config.getOrThrow("AWS_REGION"),
          },
        },
        defaultDisk: config.get("EXCEL_DEFAULT_DISK", "local"),
      }),
    }),
  ],
})
export class AppModule {}

The useFactory function can also be async and return a Promise<ExcelModuleOptions>:

ExcelModule.forRootAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: async (config: ConfigService) => {
    const bucket = await fetchBucketNameFromVault();
    return {
      disks: {
        s3: { driver: "s3", bucket, region: config.getOrThrow("AWS_REGION") },
      },
      defaultDisk: "s3",
    };
  },
});

Options Reference

ExcelModuleOptions

Option	Type	Default	Description
`defaultType`	`"xlsx" \| "csv"`	`"xlsx"`	Fallback output type when the file extension is unrecognized.
`tempDirectory`	`string`	OS temp dir	Directory used for temporary files during processing.
`csv`	`CsvSettings`	see below	Global CSV formatting defaults, applied when no per-export override exists.
`disks`	`Record<string, DiskConfig>`	--	Named storage backend configurations. See Storage Drivers.
`defaultDisk`	`string`	`"local"`	The disk name used when `disk` is omitted from service method calls.

CsvSettings

These settings control how CSV files are generated. They can be set globally via the csv option, or overridden per-export using the WithCsvSettings concern.

Option	Type	Default	Description
`delimiter`	`string`	`","`	Column delimiter character.
`quoteChar`	`string`	`"\""`	Character used to quote fields.
`lineEnding`	`string`	`"\n"`	Line ending sequence.
`useBom`	`boolean`	`false`	Prepend a UTF-8 byte-order mark to the output.
`encoding`	`BufferEncoding`	`"utf-8"`	Output character encoding.

ExcelAsyncOptions

Option	Type	Description
`imports`	`any[]`	Modules to import (e.g., `[ConfigModule]`).
`inject`	`any[]`	Providers to inject into `useFactory`.
`useFactory`	`(...args: any[]) => ExcelModuleOptions \| Promise<ExcelModuleOptions>`	Factory function that returns the module options.

File Type Detection

When you call a service method with a filename (e.g., download(exportable, "report.xlsx")), the library detects the output type from the file extension:

Extension	Resolved Type
`.xlsx`	`ExcelType.XLSX`
`.csv`	`ExcelType.CSV`
other	Falls back to `defaultType`

You can always override automatic detection by passing an explicit writerType or readerType argument:

import { ExcelType } from "@nestbolt/excel";

await this.excelService.download(exportable, "report.dat", ExcelType.XLSX);

Providers Exported by the Module

ExcelModule exports two providers, both available globally after registration:

Provider	Description
`ExcelService`	The main service for exports and imports.
`DiskManager`	Direct access to storage drivers for manual file operations (put, get, delete, exists).

import { ExcelService, DiskManager } from "@nestbolt/excel";

@Injectable()
export class ReportService {
  constructor(
    private readonly excelService: ExcelService,
    private readonly diskManager: DiskManager,
  ) {}
}

On this page