Getting started with client-side JS

Django Javascript Python Node.js / Next.js / React

The Shellviz JavaScript library can be used directly in the browser, either from a CDN or by importing it as an ES Module. For Node.js usage, see the Node.js / Next.js / React guide.

Note:

This page covers browser-specific features. For a full API reference, please see the Node.js / Next.js / React documentation.

Installation

Browser (CDN)

Include the library with a <script> tag. The shellviz global object will be available.

<script src="https://unpkg.com/shellviz@0.5.0-beta.3"></script>

Note:

The @0.5.0-beta.3 modifier can be removed once version 0.5 is released

Browser (ES Modules)

Import the library as an ES Module.

<script type="module">
import { log, table, show } from 'https://unpkg.com/shellviz@0.5.0-beta.3/dist/browser.mjs';
</script>

Build Tools (Webpack, Vite, etc.)

Install via npm and import in your bundled application:

npm install shellviz

import { log, table, show } from 'shellviz';

show();
log('Hello from bundled application!');

Quick Start

<!DOCTYPE html>
<html>
<head>
    <title>Shellviz Browser Example</title>
</head>
<body>
    <script src="https://unpkg.com/shellviz"></script>
    <script>
        const { log, table, show } = shellviz;
        
        // Show the floating widget
        show();
        
        // Send data to visualization
        log('Hello from the browser!');
        table([['Name', 'Value'], ['Test', 123]]);
    </script>
</body>
</html>

The browser widget is a floating, resizable panel that displays visualizations directly in the browser.

Floating Panel: Non-intrusive overlay that doesn't affect page layout
Resizable: Drag handles to resize width and height
Persistent: Remembers size and expansion state across page reloads
Collapsible: Click chevron to minimize to a small bubble
Auto-show: Automatically appears when data is first sent

import { show } from 'shellviz';
show(); // Display the floating widget

Configuration

Window Variables

Configure Shellviz before importing by setting global window variables:

<script>
    // Set before importing Shellviz
    window.SHELLVIZ_PORT = 8080;
    window.SHELLVIZ_URL = "https://my-server.com";
</script>
<script src="https://unpkg.com/shellviz"></script>

Constructor Parameters

import { ShellvizClient } from 'shellviz';

const client = new ShellvizClient({
    port: 8080,
    url: 'http://my-remote-server.com'
});

client.show();
client.log('Custom configuration');

Configuration Priority

Constructor parameters (highest priority)
Window variables (window.SHELLVIZ_*)
Default values (port: 5544)

How It Works

In the browser, Shellviz runs entirely client-side by:

Implementing a local server that mimics the Node.js API
Intercepting network calls to handle them locally
Running an embedded React app for visualization

// These calls work entirely in the browser
log('Browser logging');
table([['Browser', 'Version'], ['Chrome', '91']]);
// No external server needed

Usage Examples

Real-time Data Updates

const { log, progress, number, show } = shellviz;
show();

let count = 0;
setInterval(() => {
    count++;
    number(count, 'counter');
    progress(Math.sin(Date.now() / 1000) * 0.5 + 0.5, 'wave');
    log(`Update ${count}`, 'updates');
}, 1000);

API Response Visualization

const { json, table, card, show } = shellviz;
show();

async function visualizeAPIData() {
    const response = await fetch('https://api.example.com/data');
    const data = await response.json();
    
    json(data, 'api_response');
    card({ total: data.items?.length || 0 }, 'summary');
}

Chart Visualizations

const { bar, pie, area, show } = shellviz;
show();

// Bar chart
const salesData = [
    { name: 'Jan', value: 4000 },
    { name: 'Feb', value: 3000 },
    { name: 'Mar', value: 5000 }
];
bar(salesData, 'monthly_sales');

// Pie chart
const deviceData = [
    { name: 'Desktop', value: 45 },
    { name: 'Mobile', value: 35 },
    { name: 'Tablet', value: 20 }
];
pie(deviceData, 'devices');

Framework Integration

React

import { useEffect, useRef } from 'react';
import { log, table, show } from 'shellviz';

function DataVisualization({ data }) {
    const shownRef = useRef(false);
    
    useEffect(() => {
        if (!shownRef.current) {
            show();
            shownRef.current = true;
        }
        
        if (data) {
            table(data, 'react_data');
        }
    }, [data]);
    
    return <div>Check Shellviz widget for visualization!</div>;
}

Vue

// Vue component
import { log, table, show } from 'shellviz';

export default {
    mounted() {
        show();
    },
    methods: {
        updateData() {
            table(this.data, 'vue_data');
        }
    }
}

Remote Server Connection

<script>
    // Connect to remote Shellviz server
    window.SHELLVIZ_URL = "https://my-shellviz-server.com";
</script>
<script src="https://unpkg.com/shellviz"></script>
<script>
    const { log, table } = shellviz;
    // Data will be sent to the remote server
    log('Hello from browser to remote server!');
</script>

NextIntroduction