Kyt Utilities

1.3.34 verified Thu Apr 23 auth: no javascript

Kyt Utilities (`kyt-utils`) is an internal utility library developed by The New York Times, forming a core component of the `kyt` ecosystem, which is a React starter kit and framework. This package provides specialized helper functions designed for internal use within `kyt`-based applications and the `kyt` build system. Its functionalities include resolving project configurations, managing webpack setup, and handling environment variables and port assignments. The current stable version is 1.3.34. While it doesn't follow an independent public release cadence, it is actively maintained as part of the larger `kyt` mono-repository. Its primary purpose is to support the `kyt` framework, making it distinct from general-purpose utility libraries.

Common errors

error Module not found: Error: Can't resolve 'kyt-utils' ↓

cause Attempting to import directly from 'kyt-utils' instead of a specific subpath that exports the desired utility.

fix

Change the import path to a specific subpath where the utility resides, for example: import { someFunction } from 'kyt-utils/utils'; or import { anotherFunction } from 'kyt-utils/config';

error TypeError: someUtilityFunction is not a function ↓

cause This usually indicates an incorrect import. You might be attempting to import a named export as a default, or importing from the wrong subpath where the function is not actually exported.

fix

Verify that you are using named imports (import { someUtilityFunction } from '...') and that the import path precisely matches where the function is exported (e.g., /utils, /webpack, /config). Consult the kyt-utils source code for the exact export definitions.

error ReferenceError: process is not defined ↓

cause Many `kyt-utils` functions, especially those related to configuration and environment, rely on Node.js-specific global objects and APIs (like `process`). This error occurs when such code is executed in a browser environment.

fix

Ensure that utilities designed for server-side or build-time execution are only consumed in Node.js environments. If you need similar functionality in the browser, consider implementing browser-compatible alternatives or relying on kyt's client-side runtime for such features.

Warnings

gotcha Kyt Utilities (`kyt-utils`) is primarily an internal package of the `kyt` framework. Its public API is not explicitly documented or guaranteed to be stable across `kyt` major versions. Direct consumption should be approached with caution as functions and their signatures may change without typical semver adherence for external consumers. ↓

fix Prefer using `kyt`'s documented APIs where possible. If direct `kyt-utils` imports are necessary, pin exact versions to avoid unexpected breaking changes with minor updates and regularly review the `kyt` monorepo's changelog.

breaking Prior to version 1.0.0, the utilities might have been exposed differently or were part of the main `kyt` package. The transition to a dedicated `kyt-utils` package (around 1.0.0) could have introduced breaking changes for existing code that relied on previous internal structures. ↓

fix Review the `kyt` monorepo's changelogs around the 1.0.0 release for `kyt-utils` for specific migration steps. Update import paths and function calls to reflect the new package structure and ensure compatibility.

gotcha Many exports from `kyt-utils` are from specific subpaths (e.g., `kyt-utils/utils`, `kyt-utils/webpack`, `kyt-utils/config`). Incorrect import paths will result in module not found errors or undefined imports, as the root `kyt-utils` package typically doesn't re-export all its internal modules directly. ↓

fix Always check the specific subpath for the utility you intend to import. Refer to the `kyt-utils` source code in the `kyt` GitHub repository for the correct export paths, or inspect the package's `package.json` and build outputs.

gotcha The package depends on `lodash`. While convenient, this adds `lodash`'s full bundle size to any client-side bundles if these utilities are inadvertently bundled for the browser. This can significantly impact client-side performance and bundle size. ↓

fix Be mindful of where `kyt-utils` is imported. Ensure that utilities relying on `lodash` are only consumed in Node.js environments (e.g., server-side rendering, build scripts) or that your build setup effectively tree-shakes unused `lodash` parts if used in browser bundles. Consider using smaller, purpose-built alternatives if not strictly within a `kyt` server-side context.

Install

npm install kyt-utils

yarn add kyt-utils

pnpm add kyt-utils

Imports

resolveCwd
wrong
```
import { resolveCwd } from 'kyt-utils'; // Incorrect subpath
const { resolveCwd } = require('kyt-utils/utils'); // CommonJS in an ESM-only context
```
correct
```
import { resolveCwd } from 'kyt-utils/utils';
```
Many `kyt-utils` exports are from specific subpaths (e.g., `/utils`, `/config`, `/webpack`), not directly from the root package. While `kyt`'s build system might use CommonJS, modern userland consumption typically uses ESM named imports.

getWebpackConfig

wrong

import getWebpackConfig from 'kyt-utils/webpack'; // Not a default export
const getWebpackConfig = require('kyt-utils/webpack'); // CommonJS import of named export

correct

import { getWebpackConfig } from 'kyt-utils/webpack';

This function is primarily used within the `kyt` build process to generate webpack configurations. It is a named export from the `/webpack` subpath and expects a configuration object as an argument.

getPort

wrong

import * as config from 'kyt-utils/config'; // While technically correct, not idiomatic for single symbol
import getPort from 'kyt-utils/config'; // Not a default export

correct

import { getPort } from 'kyt-utils/config';

Used for resolving an available network port, commonly for development servers. This utility is exported as a named export from the `/config` subpath and takes an options object (e.g., `{ port, host }`).

Quickstart

Demonstrates how to import and utilize core `kyt-utils` functions for tasks such as resolving the project root, loading application configurations, and dynamically finding an available network port for development.

import { resolveCwd, resolveAppConfig } from 'kyt-utils/utils';
import { getPort } from 'kyt-utils/config';

// Resolve the current working directory of the project.
const projectRoot = resolveCwd();
console.log(`Project root resolved to: ${projectRoot}`);

// Resolve the application-specific configuration. This typically involves
// loading and merging various config files based on environment.
const appConfig = resolveAppConfig();
console.log('Resolved Application Config:', appConfig);

// Asynchronously find an available port, often for a development server.
// getPort typically returns a Promise that resolves with an available port.
async function findAndLogPort() {
  try {
    const suggestedPort = parseInt(process.env.PORT ?? '3000', 10);
    const availablePort = await getPort({ port: suggestedPort, host: 'localhost' });
    console.log(`An available port found at: ${availablePort}`);
  } catch (error) {
    console.error('Failed to find an available port:', error instanceof Error ? error.message : String(error));
  }
}

findAndLogPort();