stacks.js

This repo is home to the stacks.js libraries which provide everything you need to work with the Stacks blockchain.

@stacks/auth Construct and decode authentication requests for Stacks apps.
@stacks/storage Store and fetch files with Gaia, the decentralized storage system.
@stacks/transactions Construct, decode transactions and work with Clarity smart contracts on the Stacks blockchain.
@stacks/cli Command line interface to interact with auth, storage and Stacks transactions.
@stacks/stacking Library for PoX stacking.
@stacks/keychain Create and manage keys/wallets for the Stacks blockchain.
@stacks/network Network and API library for working with Stacks blockchain nodes.
@stacks/encryption Encryption functions used by stacks.js packages.
@stacks/profile Functions for manipulating user profiles.
@stacks/common Common utilities used by stacks.js packages.
@stacks/bns Library for interacting with the BNS contract.
@stacks/wallet-sdk Library for building wallets for the Stacks blockchain.

See README in each package directory for installation instructions and usage.

Importing & Polyfills

Most of the stacks.js packages are released in multiple different forms. These typically include:

commonjs under /dist
esm under /dist/esm
umd (with all dependencies bundled and polyfilled for the browser) under /dist/umd
an additional esm bundle (with external dependecies bundled and polyfilled for the browser) under /dist/polyfill

Build systems try to be smart and auto-detect the correct type. But you can specify which type to import as follows:

import { generateSecretKey } from '@stacks/wallet-sdk'; // auto-detect
import { generateSecretKey } from '@stacks/wallet-sdk/dist/polyfill'; // esm bundle
const walletSdk = require('@stacks/wallet-sdk'); // auto-detect
const walletSdk = require('@stacks/wallet-sdk/dist/umd'); // umd bundle
// ...

The following package types have been observed to work well out-of-the-box with common frameworks.

Framework	Import Type
React	`/dist/umd`
Next.js	auto-detect
Vue	`/dist/umd`
Svelte	`/dist/polyfill`

For production builds it is recommended to configure the respective build system to optimize further. For more fine-grained control, import using esm and configure your build system to polyfill any necessary dependencies. You could also alias the packages to their /dist/<TYPE> alternative. E.g., if you are already polyfilling in webpack, add a resolve.alias section like this.

We are currently working to get rid of many dependencies to remove the need for complex configuration. For now, if you are seeing problems, try the /dist/umd import. Otherwise, open a new issue with details on your build setup.

We're currently seeing some problems with the /dist/polyfill of the @stacks/encryption package — use the /dist/umd imports here instead.

Migrating from blockstack.js

To migrate your app from blockstack.js to stacks.js follow the steps in the migration guide.

Development: environment setup

To setup the development environment for this repository, follow these steps:

Prerequisites:

Node v16.x.x is recommended (Node v17 may run into issues that can be worked around)

Clone this package.
Run npm install to install dependencies
Run npm run bootstrap to bootstrap project
Run npm run build to build packages
Run npm run test to run tests
🚀

Some tests may contain logging of errors and warnings. This should not be confused with failing tests. Make sure the last lines of npm run test show lerna success - @stacks/... for every package.

Development: adding dependencies

This repo uses Lerna hoisting for package dependencies.

In order to install a new dependency to a package, the lerna add command must be used, rather than npm install <package>.

For example, the following command installs lodash as a dependency to the @stacks/storage package:

# Run within the root directory
npx lerna add lodash --scope @stacks/storage

Add --dev to install as a development dependency:

npx lerna add lodash --scope @stacks/storage --dev

Documentation

Documentation for the stacks.js packages is located at stacks.js.org.

Contributing

Github issues marked help-wanted are great places to start. Please ask in a github issue or discord before embarking on larger issues that aren't labeled as help wanted or adding additional functionality so that we can make sure your contribution can be included!