@dfinity/principal

What is @dfinity/principal?

@dfinity/principal is an npm package used for handling Principal IDs in the DFINITY Internet Computer ecosystem. It provides utilities for creating, parsing, and validating Principal IDs, which are unique identifiers for canisters and users on the Internet Computer.

What are @dfinity/principal's main functionalities?

Create a Principal

This feature allows you to create a Principal object from a text representation. The code sample demonstrates how to create a Principal from a text string and then convert it back to a text representation.

const { Principal } = require('@dfinity/principal');
const principal = Principal.fromText('aaaaa-aa');
console.log(principal.toText());

Validate a Principal

This feature is used to validate a Principal ID. The code sample shows how to attempt to create a Principal from a text string and handle any errors if the Principal is invalid.

const { Principal } = require('@dfinity/principal');
try {
  const principal = Principal.fromText('aaaaa-aa');
  console.log('Valid Principal:', principal.toText());
} catch (error) {
  console.error('Invalid Principal:', error);
}

Convert Principal to Uint8Array

This feature allows you to convert a Principal to a Uint8Array, which is useful for low-level operations or when working with binary data. The code sample demonstrates this conversion.

const { Principal } = require('@dfinity/principal');
const principal = Principal.fromText('aaaaa-aa');
const bytes = principal.toUint8Array();
console.log(bytes);

Other packages similar to @dfinity/principal

principal-js

principal-js is a JavaScript library for handling Principal IDs similar to @dfinity/principal. It provides basic functionalities like creating and validating Principal IDs. However, it may not be as tightly integrated with the DFINITY ecosystem as @dfinity/principal.

README

@dfinity/principal

JavaScript and TypeScript library to work with Internet Computer Principals

Do you want to know more about developing on the Internet Computer? Visit the Developer Docs.

Additional API Documentation can be found here.

Installation

Using Principal:

npm i --save @dfinity/principal

In the browser:

import { Principal } from '@dfinity/principal';

Changelog

[3.1.0] - 2025-07-24

• feat: export the getCrc32 function from @dfinity/principal