shellviz

Shellviz Javascript Package

Installation

npm install shellviz

Usage

import { log } from 'shellviz';
log('hello world')

You can also import other visualizations, and you can choose to import using CommonJS or EJS

const { json, table } = require('shellviz')
json({ test: 'data', timestamp: new Date().toISOString() });
table([
    ['Name', 'Value'],
    ['Test', 123],
    ['Another', 'value']
]); 

The package can be importer on both the Node.JS and browser-facing/client side, however due to limitations on the browser-side it can only send data to an existing Shellviz server that has been initialized by the Node.JS or Python library

Basic Client-Side Usage:

<script src="https://unpkg.com/shellviz"></script>
<script>
const { log } = shellviz;
log('hello from the browser');
</script>

Or via Module:

<script type="module">
    import Shellviz from 'https://unpkg.com/shellviz/dist/browser.mjs';
    const s = new Shellviz()
    s.log('hello world')

    // or

    import { log, json } from 'https://unpkg.com/shellviz/dist/browser.mjs'
    log('hello world')
</script>

Building

To build the package locally:

• First, build the client:

cd client
npm install
npm run build

• Then build the Node.js package:

cd libraries/js
npm install
npm run build

• To create a local package for testing:

npm run pack  # Creates shellviz-x.x.x.tgz in the ../build directory

• To test locally, you can create a test directory and install the package:

mkdir test
cd test
npm init -y
npm install ../../build/shellviz-x.x.x.tgz

• Create a test file (e.g., test.js or test.mjs) and run it:

# For CommonJS
node test.js

# For ES Modules
node test.mjs

• To test in the client side, create a simple React app and import the client

npx create-react-app test-web
cd test-web
npm install ../../build/shellviz-x.x.x.tgz

Alternatively, to test during development you can do the following:

<!-- Add this to the website you wish to test the client-side instance in -->
<script src="http://localhost:4005/build/browser_client.umd.js"></script>```

and compile and serve the client & js library:

```bash
npm run build
python -m http.server 4005```

This isn't the optimal way of developing, as you will need to re-build on each change. We should have a better solution in place soon


The package supports both CommonJS and ES Modules, so you can use either `require()` or `import` syntax in your code.

## Deploying

To deploy the package to npm:

### 🔐 1. Authenticate with npm
Make sure you have an npm account and are logged in:
```bash
npm login

🔁 2. Bump the version

✅ For a stable release:

Use one of the following depending on the type of change:

npm version patch  # e.g., 1.0.0 → 1.0.1 (bug fixes)
npm version minor  # e.g., 1.0.0 → 1.1.0 (new features, backwards-compatible)
npm version major  # e.g., 1.0.0 → 2.0.0 (breaking changes)

🧪 For a beta/alpha/pre-release version:

Use the --preid flag to specify the pre-release tag:

Start from a stable version:

npm version prerelease --preid=beta   # e.g., 1.0.0 → 1.0.1-beta.0

Or from an existing beta:

npm version prerelease --preid=beta   # e.g., 1.0.1-beta.0 → 1.0.1-beta.1

You can also combine with minor or major if needed:

npm version minor --preid=beta   # e.g., 1.0.1 → 1.1.0-beta.0
npm version major --preid=beta   # e.g., 1.1.5 → 2.0.0-beta.0

🧱 3. Build the package

Build and verify your output:

npm run build
npm pack   # creates a tarball to inspect before publishing

🚀 4. Publish to npm

For stable releases:

npm publish

For beta/pre-release versions:

Publish under a separate tag to avoid affecting the latest version:

npm publish --tag beta

This allows users to explicitly opt-in:

npm install shellviz@beta

You can also use other tags like alpha, next, or experimental.

You can promote a tested beta to latest later using:

npm dist-tag add shellviz@1.1.0-beta.3 latest




# ShellViz JavaScript Configuration

ShellViz JavaScript libraries support configuration through environment variables (Node.js) and window objects (browser) with a clear fallback hierarchy.

## Configuration Hierarchy

1. **Constructor parameters** (highest priority)
2. **Environment Variables** (`process.env` in Node.js)
3. **Window Variables** (`window.SHELLVIZ_*` in browser)
4. **Default Values** (visible in function declarations)

## Available Configuration Options

### Environment Variables (Node.js)

All environment variables are prefixed with `SHELLVIZ_`:

- `SHELLVIZ_PORT` - Port number for the server (default: 5544)
- `SHELLVIZ_SHOW_URL` - Whether to show URL on startup (default: true)
- `SHELLVIZ_URL` - Custom base URL for the server (default: None, constructs from port)

### Window Variables (Browser)

For browser environments, you can set global variables:

```javascript
// Set these before importing ShellViz
window.SHELLVIZ_PORT = 8080;
window.SHELLVIZ_SHOW_URL = false;
window.SHELLVIZ_URL = "https://my-custom-domain.com";

Environment Variable Examples (Node.js)

# Set port to 8080
export SHELLVIZ_PORT=8080

# Disable URL display on startup
export SHELLVIZ_SHOW_URL=false

# Use a custom URL
export SHELLVIZ_URL="https://my-remote-shellviz.com"

# Run your JavaScript application
node my_script.js

Usage Examples

JavaScript Client

import { ShellvizClient } from 'shellviz';

// Uses defaults: port=5544, url=undefined
// Overridden by process.env or window vars if present
const sv = new ShellvizClient();

// Override specific settings
const sv = new ShellvizClient({ port: 9000, url: "https://my-server.com" });

JavaScript Server

import ShellvizServer from 'shellviz/server';

// Uses defaults: port=5544, showUrl=true
// Overridden by process.env if present
const server = new ShellvizServer();

// Override settings
const server = new ShellvizServer({ port: 9000, showUrl: false });

Cross-Platform Support

The configuration system works seamlessly across different environments:

Node.js Environment

• Checks process.env.SHELLVIZ_* variables
• Full server and client functionality available

Browser Environment

• Checks window.SHELLVIZ_* variables
• Client functionality available (no local server)
• Safe fallbacks prevent crashes

Webpack/Bundler Environment

• Uses compile-time environment variables if available
• Falls back to window variables or defaults

Configuration Implementation

The configuration values are computed once when the module is imported:

// In your code, you can import the computed values directly:
import { SHELLVIZ_PORT, SHELLVIZ_SHOW_URL, SHELLVIZ_URL } from 'shellviz/config';

// These will be null if not set via process.env or window
console.log(SHELLVIZ_PORT);      // e.g., 8080 or null
console.log(SHELLVIZ_SHOW_URL);  // e.g., false or null  
console.log(SHELLVIZ_URL);       // e.g., "https://my-server.com" or null

Boolean Values

For boolean configuration values, the following are considered true:

• true (boolean)
• "true" (string)
• "1" (string)
• "yes" (string)

All other values are considered false.

Default Values

Default values are clearly visible in the constructor declarations:

// Client defaults
constructor(opts = {}) // port defaults to 5544 from opts or DEFAULT_PORT

// Server defaults  
constructor({ port = 5544, showUrl = true } = {})

Environment variables and window variables automatically override these defaults when present.

Browser Integration Example

<!DOCTYPE html>
<html>
<head>
    <script>
        // Set config before importing ShellViz
        window.SHELLVIZ_PORT = 8080;
        window.SHELLVIZ_URL = "https://my-shellviz-server.com";
    </script>
</head>
<body>
    <script type="module">
        import { ShellvizClient } from './path/to/shellviz/client.js';
        
        // Will use the window variables set above
        const sv = new ShellvizClient();
        sv.log("Hello from browser!");
    </script>
</body>
</html>