@splunk/create

What is @splunk/create?

@splunk/create generates code and scaffolding for a new Splunk application, built with React, via CLI.

By using @splunk/create, you can quickly start developing with Splunk provided packages such as @splunk/react-ui, @splunk/dashboard-core, and @splunk/visualizations.

What will you create? Check out our Examples Gallery for inspiration.

Standalone mode: If you want to create a standalone React app with Splunk UI tooling (without the Splunk app monorepo), use npx @splunk/create --mode=standalone. See the Standalone App guide for details.

Requirements

• Yarn >= 1.2
• Node >= 22

Prerequisites

To run your Splunk app locally you will need a local Splunk Enterprise instance with $SPLUNK_HOME set.

For more information on getting a local instance, see the Splunk Enterprise downloads page.

Setting up $SPLUNK_HOME

# Set SPLUNK_HOME to point to the top-level installation directory
$ export SPLUNK_HOME=/opt/splunk

# Add $SPLUNK_HOME/bin to the shell’s path.
$ export PATH=$SPLUNK_HOME/bin:$PATH

Getting started

To generate files for a Splunk app, run npx @splunk/create from an empty project folder.

$ mkdir project-folder
$ cd project-folder
$ npx @splunk/create
#? What do you want to name your Splunk app?: MySplunkApp
#? What do you want to name your new page?: MyPage
#? What type of page would you like to create?: Add a Basic Page

Next, install project dependencies:

$ yarn && yarn build

You’ll now have two main directories, one for the created React page and one for the created Splunk app.

• packages/my-page
• packages/my-splunk-app

Splunk demo

Splunk demo will allow you to view your new app inside your local Splunk instance:

# navigate to your app folder
$ cd packages/my-splunk-app

# link the app to your local Splunk instance
$ yarn link:app

# check that the link is set (optional)
$ ls -l $SPLUNK_HOME/etc/apps/my-splunk-app

# restart Splunk (will start Splunk if not already started)
$ splunk restart

# navigate to the root project directory
$ cd ../../

# start the Splunk app
$ yarn start

This will watch both your my-splunk-app and my-page folders for changes and rebundle.

You should now see your app in the left hand menu of the Splunk Enterprise home page, typically located at https://localhost:8000.

There is no hot-reloading within Splunk, you'll need to manually refresh the page to see changes.

If you are not seeing your changes you can try:

• hard reloading Shift+Command+R (Ctrl+Shift+R on Windows) in Google Chrome
• disabling Splunk asset cache (not recommended for production environments)
• using https://localhost:8000/en-US/_bump

Local React demo

Sometimes developing within Splunk is not the most efficient, which is why we also provide a local development environment specifically for your React page.

# navigate to the page directory
$ cd packages/my-page

# start the local development demo
$ yarn run start:demo

Go to http://localhost:8080/ to see your new React page in action.

Page files are located in packages/my-page/src. Make a change to a file to see it update in the demo.

What’s next

• Check out our tutorials -> Tutorial: Creating a todo list
• Learn about the dev tools available in your new project -> Dev Tools
• Learn more about how your Splunk app is set up -> Generated Splunk app code
• Learn how to package your Splunk app -> Packaging a @splunk/create app
• Check out examples for inspiration -> Examples Gallery

Dashboard Studio Extension mode

Use --mode=dashboard-studio-extension to scaffold a custom visualization project for Splunk Dashboard Studio. Custom visualizations run inside a sandboxed <iframe> embedded in the dashboard and communicate with Studio via the @splunk/dashboard-studio-extension API.

Requirements

• Node >= 22
• Yarn >= 1.22

No local Splunk instance is required for development. The build output is packaged into a .spl file and installed into Splunk separately.

Getting started

Create an empty directory and run @splunk/create with the dashboard-studio-extension mode:

$ mkdir my-custom-viz
$ cd my-custom-viz
$ yarn create @splunk/create@latest --mode=dashboard-studio-extension
#? Project name: my_custom_viz
#? Visualization label (display name): My Custom Viz
#? Description: A custom visualization for Splunk Dashboard Studio
#? Author: Your Name
#? Choose a template: JavaScript

Project names must use only letters, numbers, dots, and underscores, and cannot start or end with a dot or underscore. This matches the naming requirements for Splunk app IDs.

Next, install project dependencies:

$ yarn

Generated project structure

my-custom-viz/
├── visualizations/
│   └── my_custom_viz/
│       ├── src/
│       │   ├── visualization.js   # entry point
│       │   └── visualization.css
│       └── config.json            # viz metadata
├── package/
│   └── app/
│       └── app.conf               # Splunk app identity
├── build-plugins/
├── build.mjs                      # esbuild build script
├── package.mjs                    # packaging script
└── package.json

Templates

| Template | Description | |---|---| | JavaScript | Framework-agnostic, uses @splunk/dashboard-studio-extension event listeners and getters | | React | React-based, uses @splunk/dashboard-studio-extension/react hooks and context provider |

Development workflow

# Watch mode — rebuilds on file changes
$ yarn dev

# Production build
$ yarn build:prod

# Package into a .spl file for installation into Splunk
$ yarn package

The dev and build scripts compile each visualization under visualizations/ into dist/<vizName>/visualization.js using esbuild.

Packaging

The yarn package command reads package/app/app.conf for app identity, stages all built visualizations, generates the required visualizations.conf and default.meta config files, and produces a .spl archive in dist/:

dist/my_custom_viz-0.1.0-abc1234.spl

Install the .spl into Splunk via Apps > Manage Apps > Install app from file, then enable the visualization in Dashboard Studio.

Using the extension API

Inside the visualization entry point, use @splunk/dashboard-studio-extension to subscribe to data and options from Studio:

import { VisualizationAPI } from ‘@splunk/dashboard-studio-extension’;

VisualizationAPI.addDataSourcesListener(
    ({ dataSources, loading }) => {
        if (loading || !dataSources?.primary?.data) return;
        const { fields, columns } = dataSources.primary.data;
        render(fields, columns);
    },
    { invokeImmediately: true }
);

For the React template, wrap your component in VisualizationExtensionProvider and use hooks:

import {
    VisualizationExtensionProvider,
    useDataSources,
} from ‘@splunk/dashboard-studio-extension/react’;

function MyViz() {
    const { dataSources, loading } = useDataSources();
    // ...
}

See the @splunk/dashboard-studio-extension README for the full API reference.