npm package: @signozhq/web-toolkit
Description: CLI tool for quick setup of OpenTelemetry logging, metrics, and tracing with SigNoz - supports both self-hosted and cloud deployments
Latest version: 0.1.0

# SigNoz Web Toolkit – OpenTelemetry Setup (Logs, Traces, Metrics)

A command-line tool to quickly scaffold OpenTelemetry instrumentation for your front-end or Node.js apps and wire it to SigNoz. Supports both self-hosted and cloud deployments.

## 🚀 Quick Start

```bash
npx @signozhq/web-toolkit
```

- Runs an interactive CLI to select signals, file type, and more
- Generates an `instrumentation/` folder with ready-to-use files

## ✨ Features

- **Logs, Traces, Metrics**: Choose any combination of signals
- **Smart Package Detection**: Detects npm/yarn/pnpm/bun and installs required deps
- **Idempotent Merges**: Detects existing setup, adds only new signals, updates index
- **Boilerplate Generation**: Creates per-signal instrumentation files
- **Zero-Config Deploy Info**: Reads SigNoz config from environment variables

## 🎯 What It Generates

The tool creates an `instrumentation/` directory with:

- `index.ts` or `index.js`: Imports all selected signals
- `logs/instrumentation.ts` or `.js`: Logs setup
- `traces/instrumentation.ts` or `.js`: Traces setup
- `metrics/instrumentation.ts` or `.js`: Metrics setup

The exact extension depends on your selected file type.

## 🌐 Configuration via Environment Variables

Set these environment variables (in your `.env`, CI, or run command):

```bash
SIGNOZ_COLLECTION_URL=<your-otlp-endpoint>   # e.g., http://localhost:4317 or https://ingest.us.signoz.cloud:443
SIGNOZ_INGESTION_KEY=<ingestion-key-if-required>  # leave empty for most self-hosted setups
```

The generated code reads these at runtime to configure exporters.

## 📖 Usage

1. Run the setup tool:

```bash
npx @signozhq/web-toolkit
```

2. Follow the prompts:

- Select signals (Logs, Traces, Metrics)
- Pick file type (TypeScript/JavaScript)
- Choose package manager if dependencies need installation
- Provide a service name

3. Import in your app (example for TypeScript):

```typescript
import "./instrumentation/index.ts";
```

### Command-line flags (skip prompts)

- `--lang=ts` or `--lang=js` to select file type
- `--logs`, `--traces`, `--metrics` to select signals

Examples:

```bash
# TypeScript files and only logs
npx @signozhq/web-toolkit --lang=ts --logs

# JavaScript files with logs and traces
npx @signozhq/web-toolkit --lang=js --logs --traces

# Provide flags with space instead of equals also works
npx @signozhq/web-toolkit --lang ts --metrics
```

### Adding to an existing instrumentation directory

If `instrumentation/` already exists, the tool will:

- Detect existing file type (`.ts`/`.js`)
- Detect existing signals in `instrumentation/{logs,traces,metrics}`
- Create files only for newly selected signals
- Update `instrumentation/index.(ts|js)` to import all signals

## 🔧 Prompts Overview

- **Signals**: Which signals to instrument
- **Package Manager**: Used to install missing dependencies
- **Service Name**: Your application/service name
- **File Type**: TypeScript or JavaScript

Deployment details are not prompted; they are read from environment variables.

## 🚨 Troubleshooting

### Permission denied when executing the CLI

If you see a permission error when running the tool:

```bash
npm cache clean --force
rm -rf ~/.npm/_npx
npx @signozhq/web-toolkit
```

Or manually set the executable bit on the built file (for local development):

```bash
chmod +x dist/index.js
```

The build scripts automatically ensure executable permissions after each build.

## 📦 Package Managers

Automatically detects and uses one of:

- npm
- yarn
- pnpm
- bun

## 🔢 Versioning and Releases (Changesets)

This project uses [Changesets](https://github.com/changesets/changesets) for versioning and publishing.

Common workflows:

```bash
# Create a changeset (select version bump type per change)
npm run changeset

# Apply versions to package.json and generate changelogs
npm run version

# Publish to npm (uses versions and changelogs from above)
npm run release

# Optional: preview published files
npm run publish:check
```

## 🔍 Common Issues

1. **Missing package.json**: Ensure you're in a Node.js project directory
2. **Permission errors**: Ensure the binary is executable or rerun the build
3. **Dependency installation fails**: Check your package manager configuration

## 🧹 Cleanup on Cancel

If you cancel during the interactive flow, the tool cleans up any partially created `instrumentation/` files.

## 🤝 Contributing

Contributions are welcome! Please open issues and pull requests.

## 📄 License

MIT License - see `LICENSE` for details.

## 🔗 Links

- [OpenTelemetry Documentation](https://opentelemetry.io/)
- [SigNoz Documentation](https://signoz.io/docs/)
- [Node.js OpenTelemetry](https://opentelemetry.io/docs/languages/nodejs/)