tessl/npm-docusaurus--utils

Node utility functions for Docusaurus packages providing URL handling, file operations, Git integration, i18n, Markdown processing, content visibility, and build utilities.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Configuration & Constants

Name: tessl/npm-docusaurus--utils
Author: tessl

Essential constants, default values, and configuration utilities used throughout the Docusaurus ecosystem. These constants provide standardized values for directory names, file names, ports, and other configuration parameters.

Capabilities

Version and Environment Constants

`NODE_MAJOR_VERSION`

Node.js major version extracted from process.versions.node.

/**
 * Node.js major version extracted from process.versions.node
 */
const NODE_MAJOR_VERSION: number;

`NODE_MINOR_VERSION`

Node.js minor version extracted from process.versions.node.

/**
 * Node.js minor version extracted from process.versions.node
 */
const NODE_MINOR_VERSION: number;

`DOCUSAURUS_VERSION`

Docusaurus core version from package.json.

/**
 * Docusaurus core version from package.json
 */
const DOCUSAURUS_VERSION: string;

Usage Examples:

import { 
  NODE_MAJOR_VERSION, 
  NODE_MINOR_VERSION, 
  DOCUSAURUS_VERSION 
} from "@docusaurus/utils";

console.log(`Node.js version: ${NODE_MAJOR_VERSION}.${NODE_MINOR_VERSION}`);
console.log(`Docusaurus version: ${DOCUSAURUS_VERSION}`);

// Check Node.js version compatibility
if (NODE_MAJOR_VERSION < 18) {
  throw new Error("Node.js 18 or higher is required");
}

// Add version info to generated metadata
const siteMetadata = {
  generator: `Docusaurus ${DOCUSAURUS_VERSION}`,
  nodeVersion: `${NODE_MAJOR_VERSION}.${NODE_MINOR_VERSION}`,
};

Directory Name Constants

`DEFAULT_BUILD_DIR_NAME`

Default build output directory name.

/**
 * Default build output directory name ("build")
 */
const DEFAULT_BUILD_DIR_NAME: string;

`SRC_DIR_NAME`

Source directory name.

/**
 * Source directory name ("src")
 */
const SRC_DIR_NAME: string;

`DEFAULT_STATIC_DIR_NAME`

Default static files directory.

/**
 * Default static files directory ("static")
 */
const DEFAULT_STATIC_DIR_NAME: string;

`OUTPUT_STATIC_ASSETS_DIR_NAME`

Build output assets directory.

/**
 * Build output assets directory ("assets")
 */
const OUTPUT_STATIC_ASSETS_DIR_NAME: string;

`GENERATED_FILES_DIR_NAME`

Generated files directory (.docusaurus or environment override).

/**
 * Generated files directory (".docusaurus" or env override)
 */
const GENERATED_FILES_DIR_NAME: string;

`THEME_PATH`

Theme components path.

/**
 * Theme components path ("src/theme")
 */
const THEME_PATH: string;

Usage Examples:

import { 
  DEFAULT_BUILD_DIR_NAME,
  SRC_DIR_NAME,
  DEFAULT_STATIC_DIR_NAME,
  OUTPUT_STATIC_ASSETS_DIR_NAME,
  GENERATED_FILES_DIR_NAME,
  THEME_PATH 
} from "@docusaurus/utils";

// Construct common paths
const siteDir = "/website";
const buildDir = path.join(siteDir, DEFAULT_BUILD_DIR_NAME);
const srcDir = path.join(siteDir, SRC_DIR_NAME);
const staticDir = path.join(siteDir, DEFAULT_STATIC_DIR_NAME);
const generatedDir = path.join(siteDir, GENERATED_FILES_DIR_NAME);

console.log("Build output:", buildDir);        // "/website/build"
console.log("Source files:", srcDir);          // "/website/src"
console.log("Static files:", staticDir);       // "/website/static"
console.log("Generated files:", generatedDir); // "/website/.docusaurus"

// Theme customization path
const themePath = path.join(siteDir, THEME_PATH);
console.log("Theme components:", themePath); // "/website/src/theme"

// Build asset output path
const assetsOutputDir = path.join(buildDir, OUTPUT_STATIC_ASSETS_DIR_NAME);
console.log("Assets output:", assetsOutputDir); // "/website/build/assets"

File Name Constants

`DEFAULT_CONFIG_FILE_NAME`

Default config file name without extension.

/**
 * Default config file name without extension ("docusaurus.config")
 */
const DEFAULT_CONFIG_FILE_NAME: string;

`BABEL_CONFIG_FILE_NAME`

Babel configuration file name.

/**
 * Babel configuration file name ("babel.config.js" or env override)
 */
const BABEL_CONFIG_FILE_NAME: string;

Usage Examples:

import { 
  DEFAULT_CONFIG_FILE_NAME,
  BABEL_CONFIG_FILE_NAME 
} from "@docusaurus/utils";

// Look for config files with different extensions
const possibleConfigFiles = [
  `${DEFAULT_CONFIG_FILE_NAME}.js`,
  `${DEFAULT_CONFIG_FILE_NAME}.ts`,
  `${DEFAULT_CONFIG_FILE_NAME}.mjs`,
];

console.log("Searching for config files:", possibleConfigFiles);
// ["docusaurus.config.js", "docusaurus.config.ts", "docusaurus.config.mjs"]

// Babel config path
const babelConfigPath = path.join(siteDir, BABEL_CONFIG_FILE_NAME);
console.log("Babel config:", babelConfigPath); // "/website/babel.config.js"

Internationalization Constants

`DEFAULT_I18N_DIR_NAME`

i18n directory name.

/**
 * i18n directory name ("i18n")
 */
const DEFAULT_I18N_DIR_NAME: string;

`CODE_TRANSLATIONS_FILE_NAME`

Code translations file name.

/**
 * Code translations file name ("code.json")
 */
const CODE_TRANSLATIONS_FILE_NAME: string;

Usage Examples:

import { 
  DEFAULT_I18N_DIR_NAME,
  CODE_TRANSLATIONS_FILE_NAME 
} from "@docusaurus/utils";

// Construct i18n paths
const siteDir = "/website";
const i18nDir = path.join(siteDir, DEFAULT_I18N_DIR_NAME);
console.log("i18n directory:", i18nDir); // "/website/i18n"

// Code translations file path
const codeTranslationsPath = path.join(i18nDir, "en", CODE_TRANSLATIONS_FILE_NAME);
console.log("Code translations:", codeTranslationsPath); // "/website/i18n/en/code.json"

// Locale-specific paths
const locales = ["en", "fr", "es"];
const translationPaths = locales.map(locale => 
  path.join(i18nDir, locale, CODE_TRANSLATIONS_FILE_NAME)
);
console.log("All translation files:", translationPaths);

Configuration Values

`DEFAULT_PORT`

Default development server port.

/**
 * Default development server port (3000 or PORT env var)
 */
const DEFAULT_PORT: number;

`DEFAULT_PLUGIN_ID`

Default plugin instance ID.

/**
 * Default plugin instance ID ("default")
 */
const DEFAULT_PLUGIN_ID: string;

`WEBPACK_URL_LOADER_LIMIT`

URL loader size limit for webpack.

/**
 * URL loader size limit (10000 or env override)
 */
const WEBPACK_URL_LOADER_LIMIT: string | number;

Usage Examples:

import { 
  DEFAULT_PORT,
  DEFAULT_PLUGIN_ID,
  WEBPACK_URL_LOADER_LIMIT 
} from "@docusaurus/utils";

// Development server configuration
const devServerConfig = {
  port: process.env.PORT || DEFAULT_PORT,
  host: "localhost",
};
console.log(`Dev server will run on port: ${devServerConfig.port}`);

// Plugin configuration
const pluginConfig = {
  id: DEFAULT_PLUGIN_ID,
  path: "./docs",
};
console.log("Default plugin ID:", pluginConfig.id); // "default"

// Webpack loader configuration
const urlLoaderConfig = {
  test: /\.(png|jpg|jpeg|gif)$/,
  use: {
    loader: "url-loader",
    options: {
      limit: WEBPACK_URL_LOADER_LIMIT,
      fallback: "file-loader",
    },
  },
};
console.log("URL loader limit:", WEBPACK_URL_LOADER_LIMIT); // 10000 (or env override)

Complete Configuration Example

import {
  DEFAULT_BUILD_DIR_NAME,
  DEFAULT_CONFIG_FILE_NAME,
  SRC_DIR_NAME,
  DEFAULT_STATIC_DIR_NAME,
  DEFAULT_I18N_DIR_NAME,
  THEME_PATH,
  DEFAULT_PORT,
  DEFAULT_PLUGIN_ID,
  DOCUSAURUS_VERSION,
  NODE_MAJOR_VERSION,
} from "@docusaurus/utils";

// Complete site configuration using constants
function createSiteConfig(siteDir: string) {
  return {
    // Version info
    version: DOCUSAURUS_VERSION,
    nodeVersion: NODE_MAJOR_VERSION,
    
    // Directory structure
    dirs: {
      site: siteDir,
      build: path.join(siteDir, DEFAULT_BUILD_DIR_NAME),
      src: path.join(siteDir, SRC_DIR_NAME),
      static: path.join(siteDir, DEFAULT_STATIC_DIR_NAME),
      i18n: path.join(siteDir, DEFAULT_I18N_DIR_NAME),
      theme: path.join(siteDir, THEME_PATH),
    },
    
    // Development server
    devServer: {
      port: DEFAULT_PORT,
    },
    
    // Plugin configuration
    plugins: [
      [
        "@docusaurus/plugin-content-docs",
        {
          id: DEFAULT_PLUGIN_ID,
          path: "./docs",
        },
      ],
    ],
    
    // Config file patterns
    configFiles: [
      `${DEFAULT_CONFIG_FILE_NAME}.js`,
      `${DEFAULT_CONFIG_FILE_NAME}.ts`,
      `${DEFAULT_CONFIG_FILE_NAME}.mjs`,
    ],
  };
}

Install with Tessl CLI