DOCSEARCHbyAlgolia
Submit Docs

filenamify

repository·main·Indexed 19 days ago

https://github.com/sindresorhus/filenamify

A utility for converting strings into valid, safe filenames by removing or replacing reserved characters, non-printable control characters, and normalizing Unicode whitespace. Version 7.0.2 provides filenamify() for string sanitization and filenamifyPath() for converting path structures into flat filenames, with configurable replacement characters and grapheme-aware maxLength truncation.

Tokens
1.6K
Snippets
10
Records
11
Agent score
67%

What's inside filenamify

  2. Use the browser-only import for web applications

    main

    If you are using a bundler like webpack and only need the filenamify function (not filenamifyPath), import from filenamify/browser. This avoids including path dependencies or polyfills required by filenamifyPath.

    import filenamify from 'filenamify/browser';

filenamify('<foo/bar>');
//=> '!foo!bar!'

  3. Configure filenamify options

    main

    Both filenamify() and filenamifyPath() accept an options object to customize the transformation behavior:

    • replacement (string, default: '!'): The string used to replace reserved characters. It cannot contain reserved characters (<, >, :, ", /, \, |, ?, *) or control characters.
    • maxLength (number, default: 100): The maximum length for the filename. Only the base of the filename is truncated, preserving the extension. Truncation is grapheme-aware to avoid splitting Unicode characters. Note: If the extension itself exceeds maxLength, the resulting string will be longer than maxLength.

  4. Convert a filename within a path with filenamifyPath()

    main

    Use filenamifyPath(path, options?) to convert only the filename portion of a path to a valid filename while preserving the rest of the path structure.

    import {filenamifyPath} from 'filenamify';

filenamifyPath('foo:bar');
//=> 'foo!bar'

  5. Convert a string to a safe filename with filenamify()

    main

    Use filenamify(string, options?) to convert a string into a valid, safe filename. It removes reserved characters (like / on Unix or <>:"/\|?* on Windows), non-printable control characters, and normalizes Unicode whitespace.

    By default, reserved characters are replaced with !.

    import filenamify from 'filenamify';

filenamify('<foo/bar>');
//=> '!foo!bar!'

filenamify('foo:"bar"', {replacement: '🐴'});
//=> 'foo🐴bar🐴'

  6. Use filenamify() to sanitize strings for filenames

    main

    Import filenamify from the package to convert a string into a safe filename by removing or replacing characters that are invalid or problematic in file systems. This is useful when you want to use user-provided text as a filename.

    import filenamify from 'filenamify';

const filename = filenamify('foo/bar:baz?');
// returns 'foobarbaz'

  7. Convert a string to a valid filename with filenamify()

    main

    Use the default export filenamify to convert a string into a valid filename by replacing reserved characters and optionally truncating the length.

    By default, reserved characters (like <, >, :, ", /, \, |, ?, * or control characters) are replaced with ! and the filename is truncated to 100 characters.

    import filenamify from 'filenamify';

filenamify('<foo/bar>');
//=> '!foo!bar!'

filenamify('foo:"bar"', {replacement: '🐴'});
//=> 'foo🐴bar🐴'

  8. Use filenamifyPath() to sanitize file paths for filenames

    main

    Import filenamifyPath from the package to convert a file path into a safe filename. Unlike filenamify, which treats the input as a single string, filenamifyPath is designed to handle path structures, making it suitable for turning a path into a single, flat filename.

    import { filenamifyPath } from 'filenamify';

const filename = filenamifyPath('foo/bar/baz.txt');
// returns 'foo-bar-baz.txt'

  9. Use filenamify() to sanitize strings for filenames

    main

    The filenamify() function converts a string into a safe filename by removing or replacing problematic characters (like control characters, reserved symbols, and relative path markers) and trimming trailing spaces or periods.

    It handles Unicode normalization (NFC), collapses multiple consecutive reserved characters into one, and ensures the resulting filename is not a Windows reserved name (e.g., CON, PRN).

    Options

    • replacement (string): The character(s) used to replace problematic parts of the string. Defaults to '!'. The replacement string cannot contain reserved filename characters or control characters (except the zero-width joiner \u200D).
    • maxLength (number): The maximum length of the filename. Defaults to 100. If a length is provided, the function attempts to truncate the filename while preserving the extension. Note that Windows compatibility checks take precedence over maxLength if truncation creates a reserved name.
    import filenamify from 'filenamify';

// Basic usage
await filenamify('foo/bar?baz.txt'); // 'foo!bar!baz.txt'

// Custom replacement
await filenamify('invalid:name', { replacement: '_' }); // 'invalid_name'

// Truncation
await filenamify('a very long filename that should be truncated.txt', { maxLength: 10 }); // 'a very! .txt'

  10. Use filenamifyPath() to convert a path to a safe filename

    main

    The filenamifyPath function takes a file path and returns a safe filename. Unlike the standard filenamify, it is specifically designed to handle path separators and directory structures, typically by converting the path into a single flat filename.

    import { filenamifyPath } from 'filenamify';

const filename = filenamifyPath('foo/bar/baz.txt');
// returns 'foo-bar-baz.txt'

  11. Use filenamify() to convert a string to a safe filename

    main

    The default export filenamify takes a string and returns a version of that string that is safe to use as a filename. It removes or replaces characters that are invalid or problematic in file systems.

    import filenamify from 'filenamify';

const filename = filenamify('foo/bar:baz?');
// returns 'foo bar baz'