setup - saltict/Demo-Docs GitHub Wiki

Environment Setup

Detailed guide for setting up the development environment for the SubWallet Services SDK.

šŸ“– Navigation

Table of Contents

System Requirements

Operating System Support

  • macOS: 10.15 (Catalina) or later
  • Windows: 10/11 with WSL2 recommended
  • Linux: Ubuntu 18.04+, Debian 10+, or equivalent

Required Software

Node.js

  • Version: 18.0.0 or higher (LTS recommended)
  • Download: nodejs.org

Verification:

node --version  # Should output v18.x.x or higher
npm --version   # Should output 8.x.x or higher

Package Managers

Choose one of the following:

npm (included with Node.js):

npm --version

Yarn (optional, but recommended):

# Install Yarn globally
npm install -g yarn

# Verify installation
yarn --version  # Should output 1.22.x or higher

pnpm (optional, fastest option):

# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version  # Should output 7.x.x or higher

Git

Verification:

git --version  # Should output git version 2.30.x or higher

Development Environment Setup

Global Tool Installation

Nx CLI (Recommended)

# Install Nx CLI globally
npm install -g @nx/cli

# Verify installation
nx --version

TypeScript (Optional)

# Install TypeScript globally (optional, project includes local version)
npm install -g typescript

# Verify installation
tsc --version

Environment Variables

Create environment configuration for development:

# Create .env file in project root
touch .env

Add the following environment variables:

# .env
NODE_ENV=development
SUBWALLET_API_URL=https://sw-services.subwallet.app
SUBWALLET_PLATFORM=webapp
SUBWALLET_CHAIN_LIST_VERSION=0.2.108

Git Configuration

Configure Git for development:

# Set global Git configuration
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Configure line endings (important for cross-platform development)
git config --global core.autocrlf input  # macOS/Linux
git config --global core.autocrlf true   # Windows

IDE Configuration

Visual Studio Code (Recommended)

Required Extensions

Install these extensions for optimal development experience:

# Install VS Code extensions via command line
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension esbenp.prettier-vscode
code --install-extension ms-vscode.vscode-eslint
code --install-extension nrwl.angular-console
code --install-extension bradlc.vscode-tailwindcss

Manual Installation:

  1. TypeScript and JavaScript Language Features - Enhanced TypeScript support
  2. Prettier - Code formatter - Code formatting
  3. ESLint - Linting and code quality
  4. Nx Console - Nx workspace management
  5. GitLens - Enhanced Git capabilities

VS Code Settings

Create or update .vscode/settings.json in the project root:

{
  "typescript.preferences.useAliasesForRenames": false,
  "typescript.preferences.renameShorthandProperties": false,
  "typescript.suggest.includeCompletionsForImportStatements": true,
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.organizeImports": true
  },
  "files.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/.nx": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/.nx": true
  }
}

Launch Configuration

Create .vscode/launch.json for debugging:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Jest Tests",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/jest",
      "args": [
        "--runInBand",
        "--testPathPattern=subwallet-services-sdk"
      ],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "env": {
        "NODE_ENV": "test"
      }
    }
  ]
}

WebStorm/IntelliJ IDEA

Configuration Steps

  1. Import Project: Open the monorepo root directory
  2. Enable TypeScript Service: File ā†’ Settings ā†’ Languages & Frameworks ā†’ TypeScript
  3. Configure Node.js: File ā†’ Settings ā†’ Languages & Frameworks ā†’ Node.js
  4. Setup Run Configurations: Run ā†’ Edit Configurations

Recommended Plugins

  • Nx Support - Nx workspace support
  • Prettier - Code formatting
  • ESLint - Code quality

Project Installation

Clone Repository

# Clone the repository
git clone https://github.com/SubWallet/subwallet-monorepos.git

# Navigate to project directory
cd subwallet-monorepos

Install Dependencies

Using npm

# Install all dependencies
npm install

# Verify installation
npm list --depth=0

Using Yarn

# Install all dependencies
yarn install

# Verify installation
yarn list --depth=0

Using pnpm

# Install all dependencies
pnpm install

# Verify installation
pnpm list --depth=0

Post-Installation Setup

Build SDK

# Build the SubWallet Services SDK
nx build subwallet-services-sdk

# Verify build success
ls -la dist/libs/subwallet-services-sdk/

Run Tests

# Run all tests for the SDK
nx test subwallet-services-sdk

# Run tests in watch mode
nx test subwallet-services-sdk --watch

Lint Code

# Lint the SDK code
nx lint subwallet-services-sdk

# Auto-fix linting issues
nx lint subwallet-services-sdk --fix

Environment Verification

Verification Script

Create a verification script to ensure everything is set up correctly:

// scripts/verify-setup.ts
import { execSync } from 'child_process';
import { existsSync } from 'fs';

interface CheckResult {
  name: string;
  status: 'pass' | 'fail';
  message: string;
}

const checks: CheckResult[] = [];

// Check Node.js version
try {
  const nodeVersion = execSync('node --version', { encoding: 'utf8' }).trim();
  const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0]);
  
  checks.push({
    name: 'Node.js Version',
    status: majorVersion >= 18 ? 'pass' : 'fail',
    message: `${nodeVersion} ${majorVersion >= 18 ? 'āœ“' : 'āœ— (requires v18+)'}`
  });
} catch {
  checks.push({
    name: 'Node.js Version',
    status: 'fail',
    message: 'Node.js not found'
  });
}

// Check npm version
try {
  const npmVersion = execSync('npm --version', { encoding: 'utf8' }).trim();
  checks.push({
    name: 'npm Version',
    status: 'pass',
    message: `${npmVersion} āœ“`
  });
} catch {
  checks.push({
    name: 'npm Version',
    status: 'fail',
    message: 'npm not found'
  });
}

// Check if node_modules exists
checks.push({
  name: 'Dependencies Installed',
  status: existsSync('node_modules') ? 'pass' : 'fail',
  message: existsSync('node_modules') ? 'node_modules found āœ“' : 'node_modules not found āœ—'
});

// Check if SDK can be built
try {
  execSync('nx build subwallet-services-sdk', { stdio: 'ignore' });
  checks.push({
    name: 'SDK Build',
    status: 'pass',
    message: 'Build successful āœ“'
  });
} catch {
  checks.push({
    name: 'SDK Build',
    status: 'fail',
    message: 'Build failed āœ—'
  });
}

// Check if tests pass
try {
  execSync('nx test subwallet-services-sdk --passWithNoTests', { stdio: 'ignore' });
  checks.push({
    name: 'Tests',
    status: 'pass',
    message: 'All tests pass āœ“'
  });
} catch {
  checks.push({
    name: 'Tests',
    status: 'fail',
    message: 'Tests failed āœ—'
  });
}

// Display results
console.log('\nšŸ” Environment Verification Results\n');
checks.forEach(check => {
  const status = check.status === 'pass' ? 'āœ…' : 'āŒ';
  console.log(`${status} ${check.name}: ${check.message}`);
});

const failedChecks = checks.filter(check => check.status === 'fail');
if (failedChecks.length === 0) {
  console.log('\nšŸŽ‰ All checks passed! Your environment is ready for development.');
} else {
  console.log(`\nāš ļø  ${failedChecks.length} check(s) failed. Please fix the issues above.`);
  process.exit(1);
}

Run the verification:

# Run verification script
npx ts-node scripts/verify-setup.ts

Manual Verification Steps

1. Check Project Structure

# Verify SDK directory structure
ls -la libs/subwallet-services-sdk/
# Should show: src/, docs/, package.json, project.json, etc.

2. Check Dependencies

# Check if SDK dependencies are installed
npm list @subwallet-monorepos/subwallet-services-sdk

3. Test SDK Import

# Create a simple test file
cat > test-sdk.js << 'EOF'
const sdk = require('./dist/libs/subwallet-services-sdk');
console.log('SDK loaded successfully');
console.log('SDK version:', sdk.default?.version || 'unknown');
EOF

# Run the test
node test-sdk.js

# Clean up
rm test-sdk.js

Troubleshooting Setup Issues

Common Issues and Solutions

Node.js Version Issues

# If using nvm (Node Version Manager)
nvm install 18
nvm use 18

# If using Homebrew (macOS)
brew install node@18
brew link node@18

Permission Issues (npm)

# Fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Or use a Node version manager like nvm

Build Issues

# Clear caches and reinstall
npm run clean  # or yarn clean
rm -rf node_modules
rm -rf dist
npm install

TypeScript Issues

# Restart TypeScript service in VS Code
# Command Palette: "TypeScript: Restart TS Server"

# Or reinstall TypeScript
npm uninstall -g typescript
npm install -g typescript@latest

Git Line Ending Issues (Windows)

# Configure Git for proper line endings
git config --global core.autocrlf true
git config --global core.eol lf

# Re-clone the repository if necessary

Platform-Specific Setup

Windows with WSL2

# Install WSL2 Ubuntu
wsl --install -d Ubuntu

# In WSL2, install Node.js via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node@18
brew link node@18

Linux (Ubuntu/Debian)

# Install Node.js via NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

šŸ”— Related Documentation

āš ļø **GitHub.com Fallback** āš ļø