framework-utils

Common errors

• TypeError: (0 , framework_utils__WEBPACK_IMPORTED_MODULE_0__.prefixNames) is not a function

  cause This typically occurs in a CommonJS environment trying to import an ESM-only library, or when a bundler incorrectly processes the module.
  fix Ensure your project's module resolution is configured for ESM. For Node.js, add `"type": "module"` to your `package.json`. For bundlers, verify that Babel or TypeScript compilation targets allow for correct ESM output and imports.

• Cannot find module 'framework-utils' or its corresponding type declarations.

  cause The package is not installed, or TypeScript cannot find its declaration files (`.d.ts`).
  fix Run `npm install framework-utils` or `yarn add framework-utils`. If TypeScript still reports an error, ensure your `tsconfig.json` includes `"moduleResolution": "Node16"` or `"Bundler"` and that `"skipLibCheck": true` isn't masking other issues. The library ships its own types.

• TS2305: Module '"framework-utils"' has no default export.

  cause Attempting to import a default export from `framework-utils` when only named exports are provided.
  fix Change `import FrameworkUtils from 'framework-utils';` to `import { prefixNames, prefixCSS } from 'framework-utils';` for specific utilities, or `import * as FrameworkUtils from 'framework-utils';` for a namespace import.

Warnings

• gotcha This library is primarily designed for ESM (ECMAScript Modules) environments and ships with TypeScript types. While CommonJS environments might work with transpilation, direct `require()` calls are not officially supported and can lead to runtime issues or incorrect type inference, especially in modern Node.js setups.
  Fix: Ensure your project uses an ESM-compatible module system (e.g., `"type": "module"` in `package.json` for Node.js, or a bundler like Webpack/Rollup for browser environments) and uses `import` statements.
• gotcha When using `prefixCSS`, be aware that it performs string manipulation on CSS. Extremely complex or malformed CSS strings, especially those relying on advanced parsing or non-standard syntax, might not be handled as expected. Always test the output with your specific CSS.
• gotcha The `framework-utils` package is specifically designed as a utility helper for framework development, often within the Daybrush ecosystem. While generic, ensure its utilities align with your project's needs to avoid unnecessary dependency or partial reimplementation if only a small fraction of its functionality is required. Consider its targeted scope before adopting.
• deprecated While not explicitly stated as deprecated, the package has not seen a version update since 1.1.0 in 2021. Users should be mindful that maintenance might be limited to critical issues or updates related to other Daybrush projects, rather than active feature development.
  Fix: Check the GitHub repository for recent commits or issues to gauge ongoing activity. Consider contributing fixes or new features if needed, or evaluate alternative, more actively maintained libraries for new projects.

Install

• npm install framework-utils npm
• yarn add framework-utils yarn
• pnpm add framework-utils pnpm

Imports

• prefixNames
  wrong:

  const { prefixNames } = require('framework-utils');

  correct:

  import { prefixNames } from 'framework-utils';

  ESM named import is the standard for this TypeScript-first library. CommonJS require() is not officially supported and may lead to undefined behavior or type errors.
• prefixCSS
  wrong:

  import * as FrameworkUtils from 'framework-utils'; FrameworkUtils.prefixCSS(...);

  correct:

  import { prefixCSS } from 'framework-utils';

  Direct named import is preferred for tree-shaking and clarity. While a wildcard import may work, it can pull in unused code if your bundler isn't configured correctly.
• All exports
  wrong:

  import FrameworkUtils from 'framework-utils';

  correct:

  import type * as FrameworkUtils from 'framework-utils'; // For type checking only
  import * as FrameworkUtilsRuntime from 'framework-utils'; // For runtime usage

  This library does not appear to have a default export. Attempting to import a default will result in an undefined value or a runtime error. Use named imports or a namespace import for all available utilities.

Quickstart

Demonstrates the core functionality of `framework-utils` by prefixing both class names and CSS selectors, highlighting common use cases for UI development.

import { prefixNames, prefixCSS } from 'framework-utils';

// Example 1: Prefixing multiple class names
const baseName = "my-component-";
const namesToPrefix = ["header", "body", "footer"];
const prefixedClassNames = prefixNames(baseName, ...namesToPrefix);

console.log(`Prefixed class names: ${prefixedClassNames}`);
// Expected output: "Prefixed class names: my-component-header my-component-body my-component-footer"

// Example 2: Prefixing CSS selectors within a style string
const cssPrefix = "app-scope-";
const rawCSS = `
.button {
  background-color: blue;
}
.text-input, .text-area {
  border: 1px solid gray;
}
/* Comments are also handled */
`;
const prefixedStyle = prefixCSS(cssPrefix, rawCSS);

console.log(`Prefixed CSS:
${prefixedStyle}`);
/* Expected output:
Prefixed CSS:
.app-scope-button {
  background-color: blue;
}
.app-scope-text-input, .app-scope-text-area {
  border: 1px solid gray;
}
*/

// Demonstrate using another utility if available (hypothetical, based on common patterns)
// As the README only shows prefixNames and prefixCSS, we focus on expanding those.
// const someOtherUtil = FrameworkUtilsRuntime.someOtherUtility();
// console.log(someOtherUtil);