Installation Problems

Overview

Installation failures typically occur due to strict npm v7+ peer dependency resolution, outdated package managers, restricted file system permissions when installing global CLI binaries, or network proxies blocking the public npm registry and CDN edge nodes.

This guide walks you through resolving all known installation issues for @asiyst/sdk and @asiyst/cli.

npm Peer Dependency Conflicts (ERESOLVE)

Problem

When installing @asiyst/sdk in projects with existing UI component libraries or React 18 / 19 release candidates, npm may abort with:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! Found: react@19.0.0-rc...
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0 || ^19.0.0" from @asiyst/sdk@2.1.0

Resolution

1. Use the legacy peer dependencies flag:

      npm install @asiyst/sdk --legacy-peer-deps

1. Or force installation if using strict lockfiles:

      npm install @asiyst/sdk --force

1. Switch to pnpm or yarn: pnpm handles non-overlapping peer dependencies cleanly without manual flags:

      pnpm add @asiyst/sdk
   
      # or
      yarn add @asiyst/sdk

Framework Version Mismatches

Next.js App Router (React 18 / 19)

If you see errors such as Cannot find module '@asiyst/sdk/client' or window is not defined, verify that:

1. The SDK is imported exclusively inside components with the "use client"; directive.

1. In next.config.js or next.config.ts, ensure @asiyst/sdk is not added to serverComponentsExternalPackages.

// components/AsiystClientProvider.tsx
"use client";
import { useEffect } from "react";
import { Asiyst } from "@asiyst/sdk";
export function AsiystClientProvider() {
  useEffect(() => {
    if (typeof window !== "undefined") {
      Asiyst.init({
        projectId: process.env.NEXT_PUBLIC_ASIYST_PROJECT_ID!,
        publicKey: process.env.NEXT_PUBLIC_ASIYST_PUBLIC_KEY!,
      }).catch(console.error);
    }
    return () => {
      Asiyst.destroy();
    };
  }, []);
  return null;
}

Global CLI Permission & EACCES Errors

Problem

When installing @asiyst/cli globally on macOS or Linux:

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/@asiyst

Resolution

Do not use sudo npm install -g as it compromises system file permissions. Instead:

1. Configure npm to use a user-owned directory:

      mkdir -p ~/.npm-global
   
      npm config set prefix '~/.npm-global'
      echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc # or ~/.zshrc
      source ~/.bashrc
      npm install -g @asiyst/cli

1. Or execute without global installation via npx:

      npx @asiyst/cli status
   
      npx @asiyst/cli validate

Network & VPN Registry Failures

If you are behind a corporate proxy, VPN, or firewall blocking npmjs.org or CDN endpoints:

1. Verify registry configuration:

      npm config get registry
   
      # Should return: https://registry.npmjs.org/

1. If behind corporate proxy:

      npm config set proxy http://proxy.company.com:8080
   
      npm config set https-proxy http://proxy.company.com:8080

CDN Script Loading Failures

If you are embedding Asiyst via the HTML CDN snippet:

<script
  src="https://cdn.asiyst.com/sdk/v1/asiyst.min.js"
  data-project-id="proj_your_id"
  data-public-key="pk_live_your_key"
  async
></script>

If the script fails to load:

1. Check if an ad blocker or browser privacy extension (e.g. uBlock Origin, Brave Shields) is blocking third-party scripts. Whitelist cdn.asiyst.com and api.asiyst.com.

1. Inspect your site's Content Security Policy (CSP) header. Ensure https://cdn.asiyst.com is included in script-src and connect-src.

Diagnostic Checklist

For more diagnostics, run npx @asiyst/cli diagnostics in your project root.