Import Ordering Convention by Code Role

This proposal redefines how we organize imports, prioritizing their function or resource type within the application. This provides immediate context about what each import brings to the file, making

Fundamental Principles

  1. Role Over Origin: The primary classification is based on the role the import plays (e.g., configuration, a type, a service, a UI component), not whether it's a third-party library or a relative path.

  2. Instant Context: By looking at the import block, a developer should quickly understand what core elements, configurations, components, or specific logic are being used.

  3. Total Consistency: These rules will be applied uniformly across all TypeScript files.

  4. Grouping and Sorting: Always group related imports by their role and sort them alphabetically within each group.

  5. Clear Separations: Use a blank line between each main import category.

New Proposed Order and Import Categories by Role

The order of import blocks should go, from top to bottom, from the most fundamental and global to the most specific to the current file or module.

1. Core Framework & Environment Libraries (// Core)

  • Description: Includes essential imports for the core functionality of the framework and for global application environment configuration. It represents the foundation upon which the application is built.

  • Contents:

    • Core Framework Functionalities: react, next/image, @nestjs/core, @nestjs/common, useState, useEffect, useMemo, typeorm, rxjs, express, nestjs-cls.

    • Global & Common Company Utilities: Libraries under the @inlaze_techlead/inlaze-common scope, and project aliases like @core/*, @shared/* that provide transversal functionalities (e.g., Environment, setCountries, getTranslation, CapitalizeFirstLetter).

    • Description: Contains imports related to the configuration, registration, and provision of specific modules or services, from both third-party libraries and company libraries (@inlaze_techlead/*) that act as "connectors" or providers at the module level.

    • Contents: Database modules (TypeOrmModule, MongooseModule), AWS modules (@inlaze_techlead/inlaze-aws), throttling modules (@nestjs/throttler), queue modules (@nestjs/bull, @nestjs/bullmq), external configuration modules (@nestjs/config), database connection services (MongoService, TypeOrmService).

3. Middleware, Interceptors, Filters, Guards, Pipes (// Middleware & Guards)

  • Description: Imports of classes or functions that modify request/response flows, handle errors, or apply access and validation rules at the application, module, or route level.

  • Contents: LoggerMiddleware, LanguageInterceptor, AllExceptionsFilter, CustomThrottlerGuard, UserMetadataInterceptor, TransformResponseInterceptor, ColumnViewInterceptor, IpInterceptor, TimeoutInterceptor.

4. Data Entities & Schemas (// Entities & Schemas)

  • Description: Imports of definitions for persistent data structures, such as TypeORM entities or Mongoose/MongoDB schemas.

  • Contents: AffiliateEntity, TrafficChannelEntity, UserPreferenceEntity, adminEntities, affiliateEntities.

5. Types, Enums & Interfaces (// Types, Enums & Interfaces)

  • Description: Imports of type definitions (type), enumerations (enum), and interfaces (interface). Prioritize explicit type keyword when importing only types.

  • Contents: IconNameEnum, CampaignFilterBarProps, TypeFilters, BaseFieldOption, FormBind, FormState, FormFieldBind, LocalAbbreviationsEnum, DialogNotificationProps, PartnerIdentificationTypeEnum, AffiliateDetails, Fields.

6. Constants, Locales & Data Files (// Constants & Data)

  • Description: Imports of collections of immutable values, localization data (languages, translations), or JSON files that act as fixed data or dictionaries.

  • Contents: languages (from locales), countries (from JSON), DATABASE_CONNECTIONS, DETAILS_SELECT_FIELDS, BULLMQ_PREFIX.

7. Decorators (// Decorators)

  • Description: Imports of custom decorators used to add metadata, configure functionalities, or modify the behavior of classes/methods/properties.

  • Contents: UserAdminData, SKIP_TRANSFORM_KEY, RequiredVisualization, VISUALIZATION_CHECKER_KEY.

8. Services & Business Logic (// Services & Business Logic)

  • Description: Imports of classes or modules that encapsulate core business logic, data manipulation operations, process orchestration, or interactions with other systems.

  • Contents: SearchPartnerLimitService, UserService, MongoAdminService, LoggerService.

9. DTOs (Data Transfer Objects) (// DTOs)

  • Description: Imports of classes or interfaces that define the structure of data for transfer between different application layers (e.g., HTTP requests/responses, inter-service communication).

  • Contents: AffiliateDetailsResponseDto, GenericResponse.

10. Utilities, Helpers & Hooks (// Utilities & Hooks)

  • Description: Imports of reusable helper functions, generic utilities, or custom hooks (in frontend) that are not central business logic but simplify repetitive tasks or encapsulate specific behaviors.

  • Contents: getPaginationFromHeaders, mapVisualizationResults, translate, getUserFullName, onlyNumbersValidation, UsePageUrls, useCompleteProfile, useConfigsFilters, useFilterSelect, useAgreementType, useFilterSearch.

11. Application Modules / Routers (// App Modules / Routers)

  • Description: Imports of main modules or components that structure the application, grouping related functionalities or defining navigation routes.

  • Contents: AppModule, CommonModule, AppRouter, ConfigModule (project-specific), CacheModule, LoggerModule, TaskModule, DatabasesModule, SubscriberModule, JwtModule.

12. Styles (// Styles)

  • Description: Imports of visual components (usually frontend) and style files (.css, .module.css, etc.) that define the visual presentation.

How to Apply These Conventions

  1. Identify by Role: For each import, carefully determine its main function or the type of resource it represents according to the defined categories.

  2. Group: Place all imports that share the same role into a single block.

  3. Internal Sorting: Within each block, sort imports:

    • First, by the complete import path.

  4. Visual Separation: Insert a blank line between each main import category for improved readability.

  5. Block Comments: Place a single-line comment (e.g., // Core) directly above each category block. Avoid commenting on every individual import; the structure already provides sufficient clarity.

// Core
import { Environment, setCountries, setLanguages, translate, getUserFullName } from "@inlaze_techlead/inlaze-common";
import { NestFactory } from "@nestjs/core";
import { ClsService } from "nestjs-cls"; // A core module service
import { initializeTransactionalContext } from "typeorm-transactional";
import { useMemo, useState } from "react"; // React hooks
import { CapitalizeFirstLetter, onlyNumbersValidation } from "@shared/utils/capitalize-first-letter.utils"; // Global utils
import { UsePageUrls } from "@core/hooks/use-page-urls"; // Global app hook
import { AwsModule } from "@inlaze_techlead/inlaze-aws"; // Company module for AWS
import { UserCommonModule } from "@inlaze_techlead/inlaze-typeorm"; // Company module for TypeORM
import { addTransactionalDataSource } from "typeorm-transactional"; // Provider function
import { BullModule as BullMqModule } from "@nestjs/bullmq"; // Third-party module
import { ConfigModule as NestConfigModule } from "@nestjs/config"; // Third-party module
import { MongooseModule } from "@nestjs/mongoose"; // Third-party module
import { ThrottlerModule } from "@nestjs/throttler"; // Third-party module
import { TypeOrmModule } from "@nestjs/typeorm"; // Third-party module
import { DataSource } from "typeorm"; // Provider dependency
import { TypeOrmService } from "@inlaze_techlead/inlaze-typeorm"; // Provider service
import type { INestApplication } from "@nestjs/common";
import type { BaseFieldOption } from "@inlaze_techlead/ui-inlaze";

// Middleware & Guards
import { AllExceptionsFilter } from "../filters/all-exception.filter";
import { CustomThrottlerGuard } from "../guards/custom-throttler.guard";
import { ColumnViewInterceptor } from "../interceptors/column-view.interceptor";
import { TransformResponseInterceptor } from "../interceptors/transform-response.interceptor";
import { UserMetadataInterceptor } from "../interceptors/user-metadata.interceptor";


// Entities
import { adminEntities } from "./admin.entities";
import { affiliateEntities } from "./clients.entities"; 

// Types, Enums & Interfaces
import type { AffiliateDetails } from "../interfaces/affiliate-details.interface";
import type { CampaignFilterBarProps, TypeFilters } from "./interfaces/campaign-filter-bar.interfaces";
import type { Fields } from "./complete-profile.types"; 


// Constants & Data
import * as languages from "@app/locales"; 
import { countries } from "./common/json";
import { DETAILS_SELECT_FIELDS } from "../constants/affiliates.constants";


// Decorators
import { SKIP_TRANSFORM_KEY } from "../decorators/skip-transform.decorator";


// Services & Business Logic
import { MongoAdminService } from "../database/mongo-admin.service";
import { SearchPartnerLimitService } from "../../search-partner-limit/services/search-partner-limit.service";
import { UserService } from "../../user/services/user.service";


// DTOs
import { AffiliateDetailsResponseDto } from "../dto/response/affiliate-details-response.dto";
import { GenericResponse } from "../dto/generic-response.dto";


// Application Modules / Routers
import { ConfigModule } from "../common/config/config.module";
import { DatabasesModule } from "../database/database.module";
import { JwtModule } from "../jwt/jwt.module";
import { LoggerModule } from "../logger/logger.module";
import { SubscriberModule } => "../subscribers/subscriber.module";
import { TaskModule } from "../tasks/task.module";


// Styles
import styles from "./campaign-filter-bar.module.css";
import stylesRegister from "../page.module.css";
PreviousNpm RegistryNextIntroduction

Last updated