Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
IconService
✓ import IconService from 'icon-sdk-js'; // For browser/React Native
// OR
const IconService = require('icon-sdk-js'); // For Node.js
✗ import { IconService } from 'icon-sdk-js'; // Incorrect named import for default export in browser
const { IconService } = require('icon-sdk-js'); // Incorrect destructuring for default export in Node.js
IconService is the default export in browser/React Native environments and the module.exports in Node.js. The library ships with TypeScript types, supporting type-safe development.
IconBuilder
✓ import IconService from 'icon-sdk-js';
const { IconBuilder } = IconService; // Accessing nested builder via default export
✗ import { IconBuilder } from 'icon-sdk-js'; // Incorrect direct named import
const IconBuilder = require('icon-sdk-js').IconBuilder; // Possible but less idiomatic if IconService is already imported
IconBuilder is an exposed property of the IconService class, not a direct top-level export. It's typically accessed via the main IconService object.
IcxTransactionBuilder
✓ import IconService from 'icon-sdk-js';
const { IconBuilder } = IconService;
const { IcxTransactionBuilder } = IconBuilder;
✗ import { IcxTransactionBuilder } from 'icon-sdk-js'; // Incorrect direct named import
Transaction builders like IcxTransactionBuilder are deeply nested under IconService.IconBuilder and must be accessed through the parent objects.
Initializes the ICON SDK, connects to a public ICON node, and fetches basic network information like block height and demonstrates ICX unit conversion.
import IconService from 'icon-sdk-js';
import HttpProvider from 'icon-sdk-js/lib/httpprovider';
const rpcUrl = process.env.ICON_RPC_URL || 'https://lisbon.net.solidwallet.io/api/v3/icon';
const provider = new HttpProvider(rpcUrl);
const iconService = new IconService(provider);
async function getNetworkInfo() {
try {
const networkInfo = await iconService.getNetworkInfo().execute();
console.log('ICON Network Info:', networkInfo);
const blockHeight = await iconService.getLastBlock().execute();
console.log('Current Block Height:', blockHeight.height);
// Example of using IconAmount for conversion
const icxAmount = IconService.IconAmount.of(100, IconService.IconAmount.Unit.ICX).toLoop();
console.log('100 ICX in Loop units:', icxAmount.toString());
} catch (error) {
console.error('Failed to retrieve network info:', error);
}
}
getNetworkInfo();
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'IconBuilder')
Attempting to destructure `IconBuilder` directly from the main `icon-sdk-js` module when using `require` or incorrect named import with `import`.
fixAccess `IconBuilder` as a property of the `IconService` object: `const IconService = require('icon-sdk-js'); const { IconBuilder } = IconService;` or `import IconService from 'icon-sdk-js'; const { IconBuilder } = IconService;` ReferenceError: fetch is not defined
Running `icon-sdk-js` in an environment (e.g., older Node.js versions or some browser environments) where the global `fetch` API is not available.
fixFor Node.js, ensure Node.js >=18.0.0. For older browsers, import a `fetch` polyfill like `whatwg-fetch`.
Error: Failed to fetch
Network issues, incorrect RPC endpoint URL, or CORS policies preventing the browser from connecting to the ICON node.
fixVerify your `rpcUrl` is correct and accessible. Ensure the ICON node is running and configured for public access. For browser apps, check server-side CORS configuration.
Audit
Dependencies
node-fetchoptionalUsed internally for HTTP requests in Node.js environment; if using an older browser, `whatwg-fetch` polyfill might be required.