Getting Started

Welcome to Go NPM SDK! This guide will help you get up and running with the SDK quickly.

Installation

Install the SDK using Go modules:

bash

go get github.com/scagogogo/go-npm-sdk

Quick Start

Here's a simple example to get you started:

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/scagogogo/go-npm-sdk/pkg/npm"
)

func main() {
    // Create npm client
    client, err := npm.NewClient()
    if err != nil {
        log.Fatal(err)
    }
    
    ctx := context.Background()
    
    // Check if npm is available
    if !client.IsAvailable(ctx) {
        fmt.Println("npm not found, installing...")
        if err := client.Install(ctx); err != nil {
            log.Fatal(err)
        }
        fmt.Println("npm installed successfully!")
    }
    
    // Get npm version
    version, err := client.Version(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("npm version: %s\n", version)
    
    // Install a package
    err = client.InstallPackage(ctx, "lodash", npm.InstallOptions{
        SaveDev: false,
        SaveExact: true,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("lodash installed successfully!")
}

Core Concepts

Client Interface

The Client interface is the main entry point for all npm operations. It provides methods for:

Package Management: Install, uninstall, update packages
Project Management: Initialize projects, manage package.json
Script Execution: Run npm scripts
Information Retrieval: Get package info, search packages
Publishing: Publish packages to registry

Context Usage

All operations accept a context.Context parameter for:

Timeout Control: Set operation timeouts
Cancellation: Cancel long-running operations
Request Tracing: Add request metadata

// Set a timeout for the operation
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := client.InstallPackage(ctx, "express", npm.InstallOptions{})

Error Handling

The SDK provides structured error types for better error handling:

err := client.InstallPackage(ctx, "nonexistent-package", npm.InstallOptions{})
if err != nil {
    if npm.IsPackageNotFound(err) {
        fmt.Println("Package not found")
    } else if npm.IsNpmNotFound(err) {
        fmt.Println("npm is not installed")
    } else {
        fmt.Printf("Other error: %v\n", err)
    }
}

Basic Operations

Check npm Availability

client, _ := npm.NewClient()
ctx := context.Background()

if client.IsAvailable(ctx) {
    fmt.Println("npm is available")
} else {
    fmt.Println("npm is not available")
}

Install npm Automatically

if !client.IsAvailable(ctx) {
    err := client.Install(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("npm installed successfully")
}

Get npm Version

version, err := client.Version(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("npm version: %s\n", version)

Initialize a Project

options := npm.InitOptions{
    Name:        "my-project",
    Version:     "1.0.0",
    Description: "My awesome project",
    Author:      "Your Name",
    License:     "MIT",
    WorkingDir:  "/path/to/project",
}

err := client.Init(ctx, options)
if err != nil {
    log.Fatal(err)
}

Install Packages

// Install production dependency
err := client.InstallPackage(ctx, "express", npm.InstallOptions{
    SaveDev:   false,
    SaveExact: true,
})

// Install development dependency
err = client.InstallPackage(ctx, "jest", npm.InstallOptions{
    SaveDev: true,
})

// Install global package
err = client.InstallPackage(ctx, "typescript", npm.InstallOptions{
    Global: true,
})

Run Scripts

// Run build script
err := client.RunScript(ctx, "build")

// Run test script with arguments
err = client.RunScript(ctx, "test", "--verbose", "--coverage")

List Packages

packages, err := client.ListPackages(ctx, npm.ListOptions{
    Global: false,
    Depth:  1,
})
if err != nil {
    log.Fatal(err)
}

for _, pkg := range packages {
    fmt.Printf("%s@%s\n", pkg.Name, pkg.Version)
}

Search Packages

results, err := client.Search(ctx, "react hooks")
if err != nil {
    log.Fatal(err)
}

for _, result := range results {
    fmt.Printf("%s@%s - %s\n", 
        result.Package.Name, 
        result.Package.Version, 
        result.Package.Description)
}

Advanced Features

Portable npm Management

Use portable npm versions without system-wide installation:

import "github.com/scagogogo/go-npm-sdk/pkg/npm"

manager, err := npm.NewPortableManager("/opt/npm-portable")
if err != nil {
    log.Fatal(err)
}

// Install Node.js 18.17.0 with npm
config, err := manager.Install(ctx, "18.17.0")
if err != nil {
    log.Fatal(err)
}

// Create client for this version
client, err := manager.CreateClient("18.17.0")
if err != nil {
    log.Fatal(err)
}

// Use the client normally
version, _ := client.Version(ctx)
fmt.Printf("Portable npm version: %s\n", version)

Package.json Management

Direct package.json file manipulation:

import "github.com/scagogogo/go-npm-sdk/pkg/npm"

pkg := npm.NewPackageJSON("./package.json")

// Load existing package.json
err := pkg.Load()
if err != nil {
    log.Fatal(err)
}

// Modify package information
pkg.SetName("my-package")
pkg.SetVersion("2.0.0")
pkg.AddDependency("lodash", "^4.17.21")
pkg.AddScript("build", "webpack")

// Save changes
err = pkg.Save()
if err != nil {
    log.Fatal(err)
}

Platform Detection

Detect the current platform for platform-specific operations:

import "github.com/scagogogo/go-npm-sdk/pkg/platform"

detector := platform.NewDetector()
info, err := detector.Detect()
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Platform: %s\n", info.Platform)
fmt.Printf("Architecture: %s\n", info.Architecture)

if info.IsLinux() {
    fmt.Printf("Linux distribution: %s\n", info.Distribution)
}

Configuration

Working Directory

Set the working directory for npm operations:

options := npm.InstallOptions{
    WorkingDir: "/path/to/project",
}

err := client.InstallPackage(ctx, "express", options)

Registry Configuration

Use custom npm registry:

options := npm.InstallOptions{
    Registry: "https://registry.npmjs.org/",
}

err := client.InstallPackage(ctx, "private-package", options)

Timeout Configuration

Set operation timeouts:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

err := client.InstallPackage(ctx, "large-package", npm.InstallOptions{})

Best Practices

Always use contexts: Pass appropriate contexts for timeout and cancellation control
Check availability first: Use IsAvailable() before performing operations
Handle errors properly: Use error type checking for specific error handling
Set working directories: Specify working directories for project-specific operations
Use structured options: Configure operations using option structs
Validate inputs: Always validate package names and versions
Clean up resources: Ensure proper cleanup of temporary files and processes

Next Steps

Installation Guide - Detailed installation instructions
Configuration - Advanced configuration options
Platform Support - Platform-specific information
API Reference - Complete API documentation
Examples - More examples and use cases

Getting Started ​

Installation ​

Quick Start ​

Core Concepts ​

Client Interface ​

Context Usage ​

Error Handling ​

Basic Operations ​

Check npm Availability ​

Install npm Automatically ​

Get npm Version ​

Initialize a Project ​

Install Packages ​

Run Scripts ​

List Packages ​

Search Packages ​

Advanced Features ​

Portable npm Management ​

Package.json Management ​

Platform Detection ​

Configuration ​

Working Directory ​

Registry Configuration ​

Timeout Configuration ​

Best Practices ​

Next Steps ​