Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 17 or higher recommended

Yarn

Version 3.0.1 (managed via packageManager)

Git

For cloning the repository

Code Editor

VSCode or your preferred editor with ESLint support

​
Installation

1

Clone the Repository

Clone the SubWallet Extension repository from GitHub:
git clone https://github.com/Koniverse/Subwallet-V2.git
cd Subwallet-V2
2

Install Dependencies

Install all package dependencies using Yarn:
yarn install
The postinstall script will automatically run after installation to set up the environment and apply patches.
3

Verify Installation

Verify that all packages are installed correctly:
yarn --version
You should see version 3.0.1 or compatible.

​
Development Build

​
Running the Development Server

Start the development build with hot-reloading: 
yarn dev
The yarn dev command is an alias for yarn watch-dev, which includes inline source maps for better debugging.

​
What Happens During Development Build?

When you run the development command:
  1. Webpack compiles the extension in development mode
  2. Watch mode monitors file changes for hot-reloading
  3. Source maps are generated for debugging
  4. Build output is placed in packages/extension-koni/build/

​
Loading the Extension in Browser

1

Open Extensions Page

Navigate to chrome://extensions/ or edge://extensions/
2

Enable Developer Mode

Toggle the “Developer mode” switch in the top-right corner
3

Load Unpacked Extension

Click “Load unpacked” and select the packages/extension-koni/build/ directory

​
Production Build

​
Full Build Process

Create a production-ready build: 
yarn build
This command performs the following operations:
1

TypeScript Compilation

Runs koni-dev-build-ts to compile TypeScript files
2

Create ZIP Archives

Generates distribution and source ZIP files
3

Rollup Bundle

Runs Rollup to create optimized bundles

​
Individual Build Commands

Build just the UI components in production mode:
yarn build:ui
This runs Webpack in production mode for the extension UI.
Build i18n locale files:
yarn build:i18n
Create distribution ZIP archives:
yarn build:zip
This creates:
  • master-build.zip - Chrome/Edge build
  • master-build-firefox.zip - Firefox build
  • master-src.zip - Source code archive
Create a GitHub Actions release build:
yarn build:release

​
Output Directories

After building, you’ll find compiled files in:
  • packages/extension-koni/build/ - Chrome/Edge extension
  • packages/extension-koni/build-firefox/ - Firefox extension
  • master-build.zip - Packaged Chrome/Edge extension
  • master-build-firefox.zip - Packaged Firefox extension

​
Code Quality

​
Linting

SubWallet Extension enforces code quality with ESLint: 
yarn lint
Always run yarn lint before committing code. The CI pipeline will fail if linting errors are present.

​
Setting Up ESLint in Your Editor

For the best development experience, configure ESLint in your editor:
Install the ESLint extension:
  1. Open Extensions (Ctrl+Shift+X)
  2. Search for “ESLint”
  3. Install the official ESLint extension
  4. Reload VSCode
The project’s .eslintrc.js will be automatically detected.

​
Testing

​
Running Tests

SubWallet uses Jest for testing: 
yarn test

​
Writing Tests

Create test files with the .spec.ts extension: 
// Example: myFeature.spec.ts
import { describe, expect, test } from '@jest/globals';

describe('MyFeature', () => {
  test('should do something', () => {
    expect(true).toBe(true);
  });
});
Tests are automatically discovered by Jest. Files matching *.spec.ts or *.test.ts patterns will be executed, except those in node_modules or matching ignore-* patterns.

​
Cleaning Build Artifacts

Remove all build artifacts and start fresh: 
yarn clean
This removes:
  • packages/extension-koni/build/
  • packages/extension-koni/build-firefox/
  • Other generated files

​
Internationalization (i18n)

SubWallet supports multiple languages. Here are the i18n-related commands: 
yarn i18n:scan
Scans the codebase for translation keys and generates mapping files.
yarn i18n:combine-locales
Combines translation files from different sources.
yarn i18n:update:ext
Updates translation files for the extension.
yarn i18n:update:web-mobile
Updates translation files for web and mobile platforms.

​
Updating Dependencies

​
Polkadot Libraries

Update all Polkadot-related dependencies: 
yarn update:polkadot-libs
This updates:
  • @polkadot/api
  • @polkadot/util
  • @polkadot/util-crypto
  • And other Polkadot ecosystem packages

​
SubWallet Libraries

Update SubWallet-specific dependencies: 
yarn update:subwallet-libs
This updates:
  • @subwallet/chain-list
  • @subwallet/keyring
  • @subwallet/ui-keyring

​
Development Workflow Best Practices

1

Create a Feature Branch

Create a new branch for your work:
git checkout -b initials-feature-name
Example: jd-add-wallet-connect
2

Make Your Changes

Develop your feature with the development server running:
yarn dev
3

Validate Your Code

Before committing, run linting and tests:
yarn lint
yarn test
4

Commit and Push

Commit your changes and push to GitHub:
git add .
git commit -m "Add feature description"
git push origin initials-feature-name
5

Create Pull Request

Create a pull request on GitHub and wait for CI to pass before requesting review.
  • Never use --force push or modify Git history
  • Always work in feature branches, not master
  • Ensure CI passes before merging PRs
  • Address all review comments before merging

​
Troubleshooting

If you encounter version issues, ensure you’re using the correct Yarn version:
corepack enable
yarn --version
The project uses Yarn 3.0.1 as specified in packageManager.
After pulling new changes, clean and reinstall:
yarn clean
yarn install
yarn dev
  1. Ensure the build completed successfully
  2. Check the correct directory is selected (build/ for Chrome, build-firefox/ for Firefox)
  3. Try removing and re-adding the extension
  4. Check browser console for errors
If Webpack dev server fails to start, check if another process is using the port:
lsof -i :port_number
kill -9 PID

​
Next Steps

Now that your development environment is set up:

Understand the Architecture

Learn about the extension’s architecture and components

View Contributing Guidelines

Read the contribution guidelines

Explore the Codebase

Browse the source code on GitHub

Join the Community

Report issues and engage with developers

Build docs developers (and LLMs) love

Get started for freeTalk to us