Convert to Valid JavaScript Identifier

1.0.0 · active · verified Sun Apr 19

The `to-valid-identifier` package provides a robust and minimalist utility to convert any given string into a syntactically valid JavaScript identifier. It ensures that the resulting identifier is unique for different inputs, effectively handling special characters, reserved keywords, and numbers. The current stable version is `1.0.0`. Maintained by Sindre Sorhus, this package adheres to best practices, ships with TypeScript types, and aims for high stability with infrequent but impactful major releases. Its core differentiator lies in its guarantee of unique identifiers, making it suitable for code generation, transpilation targets, and dynamic variable/property naming where collisions or invalid syntax are critical concerns.

Common errors

```
TypeError: toValidIdentifier is not a function
```
cause Attempting to call `toValidIdentifier` after importing it incorrectly as a named export from an ESM module, resulting in `undefined`.

fix Change your import statement from `import { toValidIdentifier } from 'to-valid-identifier';` to `import toValidIdentifier from 'to-valid-identifier';`.
```
TypeError: (0 , to_valid_identifier__WEBPACK_IMPORTED_MODULE_0__.toValidIdentifier) is not a function
```
cause This Webpack/Babel error indicates that a named export was expected but the module provided a default export instead. Similar to the 'is not a function' error, it's an incorrect import.

fix Adjust the import statement in your source file to use the default import syntax: `import toValidIdentifier from 'to-valid-identifier';`.
```
Error: 'require('to-valid-identifier')' is not a function
```
cause In a CommonJS environment, you are trying to destructure the default export, or treating the entire `require()` result as a function when it's an object.

fix Use `const toValidIdentifier = require('to-valid-identifier');` to correctly assign the directly exported function. Do not use destructuring like `const { toValidIdentifier } = require('to-valid-identifier');`.
```
Error: The 'to-valid-identifier' package requires Node.js version 20 or greater.
```
cause The runtime Node.js version is older than the minimum requirement specified by the package (Node.js 20).

fix Update your Node.js installation to version 20 or later using a version manager like `nvm` or by downloading the latest LTS from the official Node.js website.

Warnings

breaking Version 1.0.0 of `to-valid-identifier` dropped support for older Node.js versions. A minimum of Node.js 20 is now required to run this package.
Fix: Upgrade your Node.js environment to version 20 or newer. If you cannot upgrade, consider using an older major version of the package (e.g., v0.x).
gotcha Prior to v1.0.0, identifiers that originally started with a number might not have been correctly handled, leading to invalid JavaScript identifier names.
Fix: Upgrade to `to-valid-identifier` v1.0.0 or later to ensure correct encoding of identifiers starting with numbers (e.g., `123name` becomes `_123name`).
gotcha The `toValidIdentifier` function is a default export. Attempting to import it using named import syntax (e.g., `import { toValidIdentifier } from 'pkg'`) will result in `undefined`.
Fix: Always use the default import syntax: `import toValidIdentifier from 'to-valid-identifier';` for ESM, or `const toValidIdentifier = require('to-valid-identifier');` for CommonJS.

Install

npm install to-valid-identifier npm
yarn add to-valid-identifier yarn
pnpm add to-valid-identifier pnpm

Imports

toValidIdentifier
wrong:
```
import { toValidIdentifier } from 'to-valid-identifier';
```
correct:
```
import toValidIdentifier from 'to-valid-identifier';
```
The `toValidIdentifier` function is exported as the default. Using named import syntax (`{ toValidIdentifier }`) will result in `undefined` or a runtime error in most ESM environments.
toValidIdentifier
wrong:
```
const { toValidIdentifier } = require('to-valid-identifier');
```
correct:
```
const toValidIdentifier = require('to-valid-identifier');
```
In CommonJS, the module directly exports the function. Destructuring (`{ toValidIdentifier }`) will result in `undefined` as the value.
toValidIdentifier (Type)
wrong:
```
import { ToValidIdentifierType } from 'to-valid-identifier';
```
correct:
```
import toValidIdentifier from 'to-valid-identifier'; // Type inference handled automatically
```
The package ships TypeScript types. When importing `toValidIdentifier` as a default export, its type is automatically inferred. There is no commonly exposed named type export from this package for its primary function.

Quickstart

This quickstart demonstrates how to import and use `toValidIdentifier` to convert various strings into valid JavaScript identifiers, showcasing its handling of special characters, reserved words, and ensuring consistent output for identical inputs.

import toValidIdentifier from 'to-valid-identifier';

// Basic conversion
console.log(toValidIdentifier('hello world')); // => 'hello$j$world'

// Handles hyphens and special characters
console.log(toValidIdentifier('my-variable-name!')); // => 'my$j$variable$j$name$a$'

// Ensures uniqueness, even for reserved words or problematic starts
console.log(toValidIdentifier('undefined')); // => '$_undefined$'
console.log(toValidIdentifier('123abc')); // => '$123abc$'

// Demonstrates consistent output for specific inputs
const input1 = 'foo-bar';
const input2 = 'foo bar';
const input3 = 'foo-bar'; // Same input, same output

console.log(`'${input1}' => ${toValidIdentifier(input1)}`);
console.log(`'${input2}' => ${toValidIdentifier(input2)}`);
console.log(`'${input3}' => ${toValidIdentifier(input3)}`);

view raw JSON →