ai/nanoid 3.0.0

3.0 Migration Guide

on GitHub

Nano ID 3.0 is the biggest release in the project history. Unfortunately, you will need to change the code of your application. But the changes are very small in most cases. In return, you will have better performance, smaller size, ES modules and TypeScript support.

Known Issues

• Only Create React App 4.0 supports dual ESM/CJS modules.

Simple Case

In simple cases, you just need to change default import to named import.

- import nanoid from 'nanoid'
+ import { nanoid } from 'nanoid'

nanoid() //=> "sSAi9F8yakJZPxOCr_WFb"
nanoid(5) //=> "ISe9l"

If you support IE, you need to transpile node_modules by Babel.

Non-secure and asynchronous Nano ID need only import changes as well.

- import nanoid from 'nanoid/non-secure'
+ import { nanoid } from 'nanoid/non-secure'

nanoid() //=> "sSAi9F8yakJZPxOCr_WFb"

- import nanoid from 'nanoid/async'
+ import { nanoid } from 'nanoid/async'

nanoid().then(id => {
  id //=> "sSAi9F8yakJZPxOCr_WFb"
})

TypeScript

Remove @types/nanoid if you have it. Nano ID now have built-in types.

npm uninstall @types/nanoid

React Native

For Expo you need to load the file by direct path:

- import nanoid from "nanoid/async"
+ import { nanoid } from "nanoid/async/index.native.js"

For the non-Expo environment:

1. Change polyfill for hardware random generator from expo-random to react-native-get-random-values.

2. Use sync Nano ID instead of async.

   + import 'react-native-get-random-values'
   
   - import nanoid from 'nanoid/async'
   + import { nanoid } from 'nanoid'
   
     async function createUser () {
       const user = new User()
   -   user.id = await nanoid()
   +   user.id = nanoid()
       return await user.save()
     }

URL-Safe Alphabet

Our default URL-safe alphabet was moved as named export to nanoid path:

- import url from 'nanoid/url'
+ import { urlAlphabet } from 'nanoid'

Custom Alphabet

Now we use the currying API to change the alphabet. It improves performance by pre-calculating some caches for a new alphabet.

We hope the new API will be more readable compare to the old unclear “generate” word.

- import nanoidGenerate from 'nanoid/generate'
+ import { customAlphabet } from 'nanoid'

+ const nanoid = customAlphabet(alphabet, 10)

- nanoidGenerate(alphabet, 10) //=> "0476921501"
+ nanoid() //=> "0476921501"

Non-secure and asynchronous APIs were also changed:

- import nanoidGenerate from 'nanoid/async/generate'
+ import { customAlphabet } from 'nanoid/async'

+ const nanoid = customAlphabet(alphabet, 10)

Custom Random Generator

Custom random generator API now is based on currying as well.

- import nanoidFormat from 'nanoid/format'
- import url from 'nanoid/url'
+ import { customRandom, urlAlphabet } from 'nanoid'

+ const nanoid = customRandom(urlAlphabet, 10, seedRandom)

- nanoidGenerate(seedRandom, url, 10) //=> "sSAi9F8yak"
+ nanoid() //=> "sSAi9F8yak"

We removed a custom random generator from asynchronous API because we didn’t see that somebody used it.

New Features

A few good reasons, why you should migrate to Nano ID 3.0:

• The size was decreased by 10% from 119 to 108 bytes.
• We got full TypeScript support. We use check-dts to test out .d.ts files.

  id: number = nanoid() // throws Type 'string' is not assignable to type 'number'.

• Nano ID now has out-of-the-box ES modules support and extra file to load Nano ID from jsDelivr (use it only for experiments, because of the bad loading performance). Dual ESM/CommonJS packaging is provided by dual-publish and will work in Node.js ≥12, webpack, Parcel, Rollup, and React Native.

  import { nanoid } from 'https://cdn.jsdelivr.net/npm/nanoid/nanoid.js'