@systaro/nexxus-ng

v2.1.2-ng20

Published

19 days ago

BaseX Angular Framework

Downloads

364

0High
0Medium
0Low

antonia.engfors

angular angular20 ui-components component-library basex framework forms dialog charts ag-grid

BaseX Frontend Framework

BaseX is a modular and extensible frontend framework built with Angular. It provides a solid foundation for building web applications emphasizing scalability, maintainability, performance, and ease of use for developers so they can focus on building features rather than boilerplate code.

Distributed publicly via npm: @systaro/nexxus-ng. Showcase: nexxus-framework.systaro.de/showcase — Get a licence: nexxus.systaro.de.

Quick Setup (npm)

npm install @systaro/nexxus-ng

Required: add the global polyfill to your src/index.html before any module loads. Some BaseX transitive deps (sockjs-client, @stomp/stompjs) reference Node-style global which doesn't exist in browsers. Without this line you'll see Uncaught ReferenceError: global is not defined:

<head>
  <!-- ...existing tags... -->
  <script>window.global = window;</script>
</head>

Then wire up BaseX in your bootstrap:

// src/app/app.config.ts
import { ApplicationConfig, importProvidersFrom } from '@angular/core';
import { BxModule } from '@systaro/nexxus-ng';

export const appConfig: ApplicationConfig = {
  providers: [
    importProvidersFrom(
      BxModule.forRoot({
        name: 'my-app',
        apiUrl: '/api',
        licenceKey: '<your-licence-key>'  // optional during development; banner shows without it
      })
    ),
  ]
};

Without a valid licenceKey, BaseX shows a persistent red banner at the top of the page. Localhost / *.local / *.test hostnames never trigger the banner — devs aren't punished. Get a key at nexxus.systaro.de.

Requirements

NodeJS 24+
Angular CLI 20+

📦 Required Dependencies

@angular/animations ^20.3.10
@angular/cdk ^20.2.12
@angular/common ^20.3.10
@angular/compiler ^20.3.10
@angular/core ^20.3.10
@angular/forms ^20.3.10
@angular/platform-browser ^20.3.10
@angular/platform-browser-dynamic ^20.3.10
@angular/router ^20.3.10
@messageformat/core ^3.4.0
@ckeditor/ckeditor5-angular ^10.0.0
@ckeditor/ckeditor5-build-classic ^44.3.0
ag-grid-angular ^34.3.1
ag-grid-community ^34.3.1
chart.js ^4.5.0
chartjs-adapter-date-fns ^3.0.0
chartjs-adapter-moment ^1.0.1
chartjs-plugin-datalabels ^2.2.0
date-fns ^4.1.0
highlight.js ^11.11.1
inputmask ^5.0.9
material-symbols ^0.39.2
moment ^2.30.1
ngx-json-viewer ^3.2.1
ngx-monaco-editor-v2 ^20.3.0
ngxtension ^7.0.2
rxjs ^7.8.2
tslib ^2.8.1
uuid ^13.0.0
zone.js ^0.15.1

Dev Dependencies

@angular-devkit/build-angular ^20.3.9
@angular-eslint/builder 20.6.0
@angular-eslint/eslint-plugin 20.6.0
@angular-eslint/eslint-plugin-template 20.6.0
@angular-eslint/schematics 20.6.0
@angular-eslint/template-parser 20.6.0
@angular/cli ^20.3.9
@angular/compiler-cli ^20.3.10
@types/jasmine ~5.1.9
@types/lodash ^4.17.13
@typescript-eslint/eslint-plugin 8.46.4
@typescript-eslint/parser 8.46.4
@types/d3 ^7.4.3
@types/inputmask ^5.0.7
@types/uuid ^10.0.0
eslint ^9.39.1
eslint-plugin-unused-imports ^4.2.0
jasmine-core ~5.12.1
karma ~6.4.4
karma-chrome-launcher ~3.2.0
karma-coverage ~2.2.1
karma-jasmine ~5.1.0
karma-jasmine-html-reporter ^2.1.0
typescript 5.9.3
typescript-eslint ^8.46.4

^ Compatible with version and higher, but not a new major version (e.g., ^1.2.3 is compatible with 1.2.3, 1.3.0, but not 2.0.0)
~ Compatible with version and higher, but not a new minor or major version (e.g., ~1.2.3 is compatible with 1.2.3, 1.2.4, but not 1.3.0 or 2.0.0)
No symbol Exact version match required (e.g., 1.2.3 is only compatible with 1.2.3)

Usage

Add BaseX to your project by adding the BaseX repository as a submodule

git submodule add "../basex/basex-frontend-framework.git" "src/basex"

🛠️ The paths are relative to your project root, adjust them as necessary.

Setup package.json with BaseX dependencies

BaseX provides a reference package.json file with all required dependencies and configuration. You can either:

Copy dependencies from the reference file to your existing package.json, or
Use it as a template when creating a new project

Required package.json configuration:

{
  "name": "your-project",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "test": "ng test",
    "lint": "ng lint"
  },
  "dependencies": {
    // Copy dependencies from references/package.json
  },
  "devDependencies": {
    // Copy devDependencies from references/package.json
  }
}

Important: The "type": "module" field is required since BaseX uses ES module syntax (import/export) in configuration files. This eliminates the MODULE_TYPELESS_PACKAGE_JSON warning and improves performance.

📋 Reference: See references/package.json for the complete list of dependencies.

Configure angular.json with required BaseX settings

BaseX provides a reference angular.json configuration that documents all required settings. While Angular CLI doesn't support extending angular.json files, you can copy the required settings from the reference file to your project's angular.json.

Key configurations to include:

a) Sass includePaths - Required for clean BaseX imports

To enable clean imports of BaseX Sass modules (e.g., @use "basex/mixins"), add the following configuration to your angular.json:

{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "options": {
            "stylePreprocessorOptions": {
              "includePaths": ["src"]
            },
            "allowedCommonJsDependencies": [
              "lodash",
              "moment",
              "@messageformat/core",
              "inputmask",
              "@ckeditor/ckeditor5-build-classic"
            ]
          }
        },
        "test": {
          "options": {
            "stylePreprocessorOptions": {
              "includePaths": ["src"]
            }
          }
        }
      }
    }
  }
}

b) Allowed CommonJS Dependencies - Suppresses build warnings

BaseX uses several CommonJS packages that need to be explicitly allowed to suppress build warnings:

lodash - Utility library
moment - Date manipulation library
@messageformat/core - Internationalization
inputmask - Input masking
@ckeditor/ckeditor5-build-classic - Rich text editor

These are already included in the example above under build.options.allowedCommonJsDependencies

c) Font Assets Configuration - Required for Roboto Flex font

BaseX includes the Roboto Flex variable font in src/basex/assets/fonts/. The @font-face declaration in BaseX styles expects the font at /assets/fonts/. You must configure angular.json to map the BaseX fonts to this path:

{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "options": {
            "assets": [
              "src/favicon.ico",
              "src/assets",
              {
                "glob": "**/*",
                "input": "src/basex/assets/fonts",
                "output": "/assets/fonts/"
              }
            ]
          }
        }
      }
    }
  }
}

⚠️ Important: Without this configuration, the Roboto Flex font will not load and the application will fall back to system fonts.

This configuration allows you to import BaseX mixins and functions using absolute paths instead of complex relative paths:

// ✅ Clean import (with includePaths configured)
@use "basex/mixins" as BaseX;

// ❌ Without configuration (requires relative paths)
@use "../../../../basex/mixins" as BaseX;

💡 Note: See angular.config.json for a complete reference configuration with all recommended settings including builder options, linting setup, and test configurations.

Install all dependencies

After setting up your package.json with the required dependencies and configuration, install them with npm:

npm install

Configure ESLint to inherit from BaseX

BaseX provides a shared ESLint configuration using the modern flat config format that enforces consistent code style across all projects using the framework. Simply import and export the BaseX config in your eslint.config.js:

// eslint.config.js
import config from "./src/basex/eslint.config.js";
export default config;

This single line gives you complete ESLint configuration with all BaseX defaults. If you need additional project-specific rules, you can extend the configuration array:

// eslint.config.js with custom overrides
import config from "./src/basex/eslint.config.js";

export default [
  ...config,
  // Add your custom configuration objects
  {
    files: ["src/app/**/*.ts"],
    rules: {
      // Your project-specific rule overrides
      "@angular-eslint/component-selector": [
        "warn",
        {
          type: ["element", "attribute"],
          prefix: "app", // Your custom prefix
          style: "kebab-case"
        }
      ]
    }
  }
];

What's included in BaseX ESLint config:

ESLint recommended rules and TypeScript strict type checking
Angular ESLint recommended rules and template accessibility
Code style rules (2-space indentation, single quotes, semicolons)
TypeScript rules (no-explicit-any, array-simple, etc.)
Explicit member accessibility enforcement (all class members must have public/private/protected)
Unused import detection via eslint-plugin-unused-imports
No extraneous classes (with decorator allowance for Angular services)
Angular selector rules (requires bx- prefix for BaseX components)
Template best practices (track-by, no-negated-async, interactive focus, etc.)

💡 Note: For detailed examples and best practices on explicit member accessibility, see the Code Quality Standards section below.

⚠️ Important: Understanding ESLint Rule Overrides

Rule overrides REPLACE, they don't MERGE:

When you override a rule for specific files, you completely replace that rule for those files. This is a critical concept:

// ❌ WRONG: Thinking rules merge
export default [
  ...config,  // BaseX allows "bx" prefix
  {
    files: ["src/app/**/*.ts"],
    rules: {
      "@angular-eslint/component-selector": [
        "warn",
        {
          prefix: ["bx", "app"]  // DON'T add "bx" thinking it merges!
        }
      ]
    }
  }
]

// ✅ CORRECT: Strict architecture enforcement
export default [
  ...config,  // BaseX allows "bx" prefix for src/basex/**
  {
    files: ["src/app/**/*.ts"],
    rules: {
      "@angular-eslint/component-selector": [
        "warn",
        {
          prefix: ["app"]  // ONLY allow project prefix in app code
        }
      ]
    }
  }
]

Why this matters:

Architectural Boundaries: BaseX components (bx- prefix) belong in src/basex/, not src/app/
Clear Ownership: If ESLint complains about a bx- component in src/app/, it's revealing an architectural problem
Don't Silence Errors: Adding bx to your app override silences valid architectural warnings
Errors Are Information: When ESLint complains, ask "Is this in the wrong place?" before "How do I make ESLint allow this?"

The rule:

src/basex/**/*.ts → Must use bx- prefix (framework code)
src/app/**/*.ts → Must use your project prefix (application code)

Strict rules enforce good architecture. Permissive rules hide problems. 🎯

Configure TypeScript to inherit from BaseX

BaseX provides a shared TypeScript configuration with strict compiler options and Angular-specific settings. Extend it in your tsconfig.json:

{
  "extends": "./src/basex/tsconfig.json",
  "compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    "outDir": "./dist/out-tsc"
  }
}

What's included in BaseX tsconfig:

Strict TypeScript compiler options
Angular compiler options (strict templates, injection parameters)
Extended diagnostics (unused standalone imports as errors)
ES2023 target with ES2022 modules
Experimental decorators and other Angular requirements

You only need to specify project-specific paths like baseUrl and outDir in your project's tsconfig.

Import BaseX styles in your app.component.scss

To enable BaseX base styles (fonts, animations, CSS variables, utility classes), import the styles module in your app component stylesheet:

@use "basex/styles" as BaseX with (
  $background-page: rgb(237, 240, 245),
  $background-content: rgb(249, 252, 255),
  $background-control: rgb(255, 255, 255),

  $font-light: rgb(119, 144, 174),
  $font-dark: var(--rgb-black-lighter),
  $font-muted: var(--rgb-grey),
  $font-disabled: var(--rgb-grey-lighter),
  $font-placeholder: var(--rgb-dust-dark),

  $brand-primary: rgb(44, 80, 103),
  $brand-primary-color: var(--rgb-white),
  $brand-secondary: rgb(50, 138, 168),
  $brand-secondary-color: var(--rgb-white),

  $brand-success: rgb(106, 186, 97),
  $brand-success-color: var(--rgb-white),
  $brand-error: rgb(244, 67, 54),
  $brand-error-color: var(--rgb-white),
  $brand-warning: rgb(230, 181, 85),
  $brand-warning-color: var(--rgb-white),
  $brand-info: rgb(51, 122, 183),
  $brand-info-color: var(--rgb-white)
);

:root {
  // Add application-specific CSS variable overrides here
  // Do NOT redefine variables already configured in @use above

  ::selection {
    color: var(--bx-brand-primary-contrast);
    background: var(--bx-brand-primary);
  }

  html {
    position: relative;
    height: 100vh;
    overflow: hidden;
    overflow: clip;
  }

  body {
    position: relative;
    height: 100vh;
    width: 100vw;
    padding: 0;
    margin: 0;
    background: var(--bx-background-content);
    font-size: var(--font-size-medium);
    line-height: var(--font-line-height);
    font-weight: var(--font-weight-normal);
    color: var(--rgb-font-dark);
    overflow: hidden;
    overflow: clip;
  }

  // Add your custom application styles here
}

Important Notes:

The @use "basex/styles" with (...) statement configures your theme and automatically creates corresponding CSS variables
Do NOT redefine these same CSS variables in your :root block - they are already set by BaseX
The :root block should only contain application-specific customizations and styles
This import is required for fonts to load correctly (includes @font-face declarations)
Use the BaseX namespace to access BaseX mixins and functions (e.g., @include BaseX.font-settings())

Import the BaseX module in your app.module.ts and pass in the environment configuration:

import { BaseXModule } from './basex/basex.module';
@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    BaseXModule.forRoot(environment)
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Bootstrap the App in your main.ts:

import {platformBrowser} from '@angular/platform-browser';
import {AppModule} from './app/app.module';

platformBrowser()
  .bootstrapModule(AppModule)
  .catch((err) => console.error(err));

Run the application:

ng serve

Angular v18 to V20 migration

This Version of BaseX has been updated to Angular v20. To take advantage of the latest features and improvements, it is mandatory to migrate your application to use this version of BaseX. Most of the migrations can be automated using Angular Schematics, but some manual work and review are required.

⚠️ It is recommended to perform these migrations in the order listed below.

💡 Note: When updating node packages during the migration to v20, you may need to use the --legacy-peer-deps flag to resolve peer dependency conflicts:
npm install --legacy-peer-deps
Why is this necessary? npm v7+ enforces strict peer dependency checking. During major Angular version migrations, some third-party packages may not have updated their peerDependencies to support Angular v20 yet (they might still declare "@angular/core": "^18.0.0" for example). Without this flag, npm will fail the installation with peer dependency errors. The --legacy-peer-deps flag tells npm to use the legacy (pre-v7) behavior, allowing installation to proceed even when peer dependency versions don't match exactly. This is safe during migration as most packages remain compatible across Angular versions.
Note: You typically only need to use this flag once during the initial migration installation. After the packages are installed, subsequent npm install commands should work normally.

⚙️ IntelliJ IDEA Configuration: If you're using IntelliJ IDEA, you need to configure the Node.js package manager setting to use npm:
Open Settings/Preferences (Ctrl+Alt+S / Cmd+,)
Navigate to Languages & Frameworks → Node.js
Set Package manager to npm
This ensures IntelliJ uses npm for package management operations instead of other package managers like yarn or pnpm.

1. Migrate to Application Builder

💪💪💪🏿💪🏿💪🏿 Manual work required

Angular v20 requires migrating from the deprecated @angular-devkit/build-angular:browser builder to the modern :application builder. This change modernizes the build system and is a prerequisite for other Angular v20 features.

1.1. Update angular.json

Change the builder and update configuration:

Before:

{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-angular:browser",
          "options": {
            "outputPath": "dist/your-project",
            "index": "src/index.html",
            "main": "src/main.ts",
            "polyfills": "src/polyfills.ts",
            "tsConfig": "tsconfig.app.json"
          },
          "configurations": {
            "development": {
              "buildOptimizer": false,
              "optimization": false,
              "vendorChunk": true,
              "extractLicenses": false,
              "sourceMap": true,
              "namedChunks": true
            }
          }
        },
        "test": {
          "builder": "@angular-devkit/build-angular:karma",
          "options": {
            "main": "src/test.ts",
            "polyfills": "src/polyfills.ts",
            "tsConfig": "tsconfig.spec.json"
          }
        }
      }
    }
  }
}

After:

{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-angular:application",
          "options": {
            "outputPath": "dist/your-project",
            "index": "src/index.html",
            "browser": "src/main.ts",
            "polyfills": [
              "zone.js"
            ],
            "tsConfig": "tsconfig.app.json"
          },
          "configurations": {
            "development": {
              "optimization": false,
              "extractLicenses": false,
              "sourceMap": true
            }
          }
        },
        "test": {
          "builder": "@angular-devkit/build-angular:karma",
          "options": {
            "polyfills": [
              "zone.js",
              "zone.js/testing"
            ],
            "tsConfig": "tsconfig.spec.json"
          }
        }
      }
    }
  }
}

Key changes:

builder: Change from :browser to :application
main → browser: Rename the entry point property
polyfills: Convert from file path string to array of package names
Remove deprecated options: buildOptimizer, vendorChunk, namedChunks
Remove main from test configuration

1.2. Delete polyfills.ts

The src/polyfills.ts file is no longer needed. Polyfills are now specified inline in angular.json:

rm src/polyfills.ts

1.3. Update TypeScript Configurations

Remove references to the deleted polyfills.ts file:

tsconfig.app.json:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/app",
    "types": []
  },
  "files": [
    "src/main.ts"
  ],
  "include": [
    "src/**/*.d.ts"
  ]
}

tsconfig.spec.json:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
    "types": [
      "jasmine"
    ]
  },
  "files": [
    "src/test.ts"
  ],
  "include": [
    "src/**/*.spec.ts",
    "src/**/*.d.ts"
  ]
}

💡 Reference: See references/angular.json for a complete example of the modern application builder configuration with all BaseX-specific settings.

2. General Cleanup

💪💪🏿💪🏿💪🏿💪🏿 Mostly automated, but reviewing is required.

ng g @angular/core:cleanup-unused-imports
ng g @angular/core:control-flow
ng g @angular/core:self-closing-tag

3. Migrate to Inject

💪💪🏿💪🏿💪🏿💪🏿 Mostly automated, but reviewing is required.

ng g @angular/core:inject

4. Migrate to Signals

💪💪💪💪💪🏿 Review and testing are essential.

ng g @angular/core:signal-input-migration
ng g @angular/core:output-migration
ng g @angular/core:signal-queries-migration

Check the official signal guide: https://angular.dev/guide/signals

5. Migrate to Standalone Components

💪💪💪🏿💪🏿💪🏿 Review and testing are essential.

ng g @angular/core:standalone

6. Bootstrap Migration to Standalone

💪💪💪💪🏿💪🏿 Critical Manual Work

After completing the standalone component migration, you must migrate from NgModule bootstrap to standalone bootstrap. This is the most fundamental architectural change in Angular v20.

6.1. Update main.ts (Recommended Hybrid Approach)

Before (NgModule Bootstrap):

// main.ts
import {platformBrowser} from '@angular/platform-browser';
import {AppModule} from './app/app.module';

platformBrowser()
  .bootstrapModule(AppModule)
  .catch((err) => console.error(err));

After (Standalone Bootstrap Structure):

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { importProvidersFrom } from '@angular/core';
import { provideHttpClient, provideAnimations } from '@angular/core';
import { BasexAppComponent } from './app/app.component';
import { AppModule } from './app/app.module';

bootstrapApplication(BasexAppComponent, {
  providers: [
    provideHttpClient(),
    provideAnimations(),
    // Import all your module configurations:
    importProvidersFrom(
      BrowserModule,
      BxModule.forRoot(environment),
      BxTranslateModule.forRoot({
        defaultLanguage: 'en',
        availableLanguages: [
          BxTranslateModule.Language('en', localeEn, localeEnExtra),
          BxTranslateModule.Language('de', localeDe, localeDeExtra)
        ]
      }),
      // ... all other BaseX modules
      AppModule  // Your simplified app modules
    )
  ]
})
  .catch(err => console.error(err));

6.2. Update App Component

Your main component must become standalone and declare all its dependencies:

@Component({
  selector: '[demo-app]',
  templateUrl: 'app.component.html',
  imports: [
    BxMainContainerComponent,
    BxMainHeaderComponent,
    BxIconComponent,
    // ... all components used in template
  ]
})
export class BasexAppComponent {
  // Component implementation
}

6.3. Simplify App Module (Hybrid Approach)

After migration, your app.module.ts becomes a clean container for your application-specific modules:

// app.module.ts - Simplified to contain only your app modules
import { NgModule } from '@angular/core';
import { AppCoreModule } from './modules/core/app.core.module';
import { AppDashboardModule } from './modules/dashboard/app.dashboard.module';
import { AppClientModule } from './modules/client/app.client.module';
// ... other app modules

@NgModule({
  imports: [
    AppCoreModule,
    AppDashboardModule,
    AppClientModule,
    // ... other app-specific modules
  ],
  providers: [
    // App-specific translation providers
    ...APP_TRANSLATION_PROVIDERS
  ]
})
export class AppModule {}

6.4. Migrate Translations to Provider Pattern

💪💪💪💪 Manual work required

With Angular v20 translations are now registered using providers. This allows for better tree-shaking and modularization of translation.

Old Pattern (Constructor-based):

// ❌ Old pattern - Don't use
@NgModule({
  // ...
})
export class AppAddressModule {
  constructor(translateService: BxTranslateService) {
    translateService.addTranslations('de', {
      NAVIGATION: {
        LINK: {
          ADDRESS: 'Adressen'
        }
      }
    });
  }
}

New Pattern (Provider-based):

Step 1: Create a separate i18n file (e.g., app.address.i18n.ts):

// app.address.i18n.ts
import {provideTranslation} from '../../../basex/modules/translate/basex.translate.module';

export const ADDRESS_TRANSLATION_PROVIDERS = [
  provideTranslation('de', {
    NAVIGATION: {
      LINK: {
        ADDRESS: 'Adressen'
      }
    }
  }),
  provideTranslation('en', {
    NAVIGATION: {
      LINK: {
        ADDRESS: 'Addresses'
      }
    }
  }),
];

Step 2: Update the module file:

// app.address.module.ts
import {NgModule} from '@angular/core';
import {ADDRESS_TRANSLATION_PROVIDERS} from './app.address.i18n';

@NgModule({
  imports: [
    // ... your imports
  ],
  providers: [
    ...ADDRESS_TRANSLATION_PROVIDERS
  ]
})
export class AppAddressModule {}

7. Update all SCSS files

💪💪💪💪🏿💪🏿 Manual work

@import has been deprecated in favor of @use. This improves readability and maintainability as "imports" are now namespaced which allows auto-completion in IDEs and avoids naming conflicts.

7.1. Basic @import to @use Migration

Before:

@import 'mixins';

.some-rule {
  @include font-settings($counterWidth: 100%);
  background: rgb-mix(var(--bx-brand-primary), var(--rgb-white), 90%);
}

After:

@use 'mixins' as BaseX;

.some-rule {
  @include BaseX.font-settings($counterWidth: 100%);
  background: BaseX.rgb-mix(var(--bx-brand-primary), var(--rgb-white), 90%);
}

7.2. Import Path Updates with includePaths

⚠️ Prerequisite: Ensure stylePreprocessorOptions.includePaths: ["src"] is configured in your angular.json (see Usage step 3).

With includePaths configured, all BaseX imports use a consistent, absolute path:

// ✅ Recommended - Clean absolute path (requires includePaths configuration)
@use "basex/mixins" as BaseX;

// ❌ Old approach - Complex relative paths (no longer needed)
@use '../basex/mixins' as BaseX;
@use '../../basex/mixins' as BaseX;
@use '../../../basex/mixins' as BaseX;
@use '../../../../basex/mixins' as BaseX;

Benefits:

Same import statement works from any file location
No need to calculate relative paths
Easy to move/refactor components
Consistent with modern Sass module best practices

7.3. Migration Checklist

Find all @import statements:

# Search for @import usage
grep -r "@import" src/app --include="*.scss"

Configure angular.json (if not already done):
- Add stylePreprocessorOptions.includePaths: ["src"] to build and test configurations
- See Usage step 3 for detailed configuration
Replace @import with @use:
- Change @import 'path' to @use "basex/mixins" as BaseX
- Use the same import statement for all files (no relative path calculation needed)
```
// Works from ANY file location in your project
@use "basex/mixins" as BaseX;
```

Update Function/Mixin Calls:

// Before
@include font-settings();
color: rgb-mix($primary, $white, 90%);
   
// After  
@include BaseX.font-settings();
color: BaseX.rgb-mix($primary, $white, 90%);

⚠️ Important Notes:

Each @use statement creates a namespace - all functions/mixins must be prefixed
With includePaths configured, always use @use "basex/mixins" as BaseX (no relative paths needed)
Use consistent namespace naming (BaseX) across all files for maintainability

BaseX CSS Variable Migration

This section documents the CSS variable renames that occurred as part of the BaseX v20 update. These are BaseX-specific changes, separate from the general Angular migration steps above.

Why the naming changed: The legacy --rgb-* prefix was used for themed variables, but this was confusing since --rgb-* is also used for the grayscale palette. The new --bx-* prefix clearly identifies BaseX theme variables. Additionally, the old light/dark background names were misleading - $background-light was actually a darker gray while $background-dark was a lighter color. The new names describe semantic PURPOSE rather than brightness.

SASS Configuration Variables

| Old | New | Note | |-----|-----|------| | $background-dark | $background-content | Main content area background (lighter) | | $background-light | $background-page | Page/container background |

Background CSS Variables

| Old | New | |-----|-----| | --rgb-background-dark | --bx-background-page | | --rgb-background-light | --bx-background-content |

Font CSS Variables

| Old | New | |-----|-----| | --rgb-font-light | --bx-font-color-light | | --rgb-font-dark | --bx-font-color-dark | | --rgb-font-muted | --bx-font-color-muted | | --rgb-font-disabled | --bx-font-color-disabled | | --rgb-font-placeholder | --bx-font-color-placeholder | | --font-family-roboto | --bx-font-family |

Brand/Signal Color CSS Variables

| Old | New | |-----|-----| | --rgb-brand-primary | --bx-brand-primary | | --rgb-brand-primary-color | --bx-brand-primary-contrast | | --rgb-brand-secondary | --bx-brand-secondary | | --rgb-brand-secondary-color | --bx-brand-secondary-contrast | | --rgb-brand-error | --bx-brand-error | | --rgb-brand-error-color | --bx-brand-error-contrast | | --rgb-brand-warning | --bx-brand-warning | | --rgb-brand-warning-color | --bx-brand-warning-contrast | | --rgb-brand-success | --bx-brand-success | | --rgb-brand-success-color | --bx-brand-success-contrast | | --rgb-brand-info | --bx-brand-info | | --rgb-brand-info-color | --bx-brand-info-contrast |

Shadow CSS Variables

| Old | New | |-----|-----| | --bx-box-shadow-drop-top | --bx-box-shadow-top | | --bx-box-shadow-drop-bottom | --bx-box-shadow-bottom | | --bx-box-shadow-drop-left | --bx-box-shadow-left | | --bx-box-shadow-drop-right | --bx-box-shadow-right |

New Variables (no migration needed)

These variables are new additions with no legacy equivalent:

--bx-background-control - Background color for form controls (default: white)
--bx-border-color - Default border color
--bx-border-radius - Default border radius (4px)
--bx-box-shadow-color - Base shadow color for all shadow variables

Migration Command

Use find-and-replace to update your SCSS files. The following patterns cover most cases:

# Find legacy variables in your project
grep -rn --include="*.scss" "rgb-background-\|rgb-font-\|rgb-brand-\|font-family-roboto\|box-shadow-drop-" src/app

Note: The --rgb-* grayscale variables (--rgb-black, --rgb-white, --rgb-grey, etc.) remain unchanged. Only the themed/branded variables were renamed to use the --bx-* prefix.

Code Quality Standards

Explicit Member Accessibility

BaseX enforces explicit access modifiers on all class members to improve code clarity and make the intended API surface explicit. The @typescript-eslint/explicit-member-accessibility rule requires public, private, or protected on all properties and methods (constructors don't require public as they're public by default).

Example:

// ❌ Bad - Missing access modifiers
export class MyComponent {
  counter = 0;
  userName = signal('John');

  incrementCounter() {
    this.counter++;
  }
}

// ✅ Good - Explicit access modifiers
export class MyComponent {
  protected counter = 0;
  protected readonly userName = signal('John');

  protected incrementCounter(): void {
    this.counter++;
  }
}

Best Practices:

Use protected for component/directive members that should only be accessible within the class and template
Use private for internal implementation details not used in templates
Use public for service methods and properties that form the public API
Use readonly with protected for signal properties to prevent reassignment