@splunk/create

@splunk/create

A tool for scaffolding new React components, Splunk applications, and more.

What is Create?

Create leverages Yeoman to scaffold React components and Splunk applications in a monorepo. See Yeoman resources for links to more detailed information about the yeoman API.

The generated monorepo is managed internally via Yarn Workspaces and Lerna. Create initializes the current directory as a monorepo if required, creating a configuration file for Lerna and a package.json that wraps common tasks. If the current directory already contains a monorepo, Create will add generated components or apps to it.

The generated component and app packages support multiple build targets: a production build, and a Splunk app demo build. The component generator also supports a standalone mode, consisting of a minimal webpage to debug and interact with the component.

Aside from React component and Splunk application scaffolding, Create is packaged with build tools, code quality presets, unit tests, and more.

How to run @splunk/create as a user

With Node installed, you may run the following anywhere on your filesystem:

$ npx @splunk/create

This will run the latest version of @splunk/create. If you would like to run a specific version, you can run:

$ npm install -g @splunk/create@X.Y.Z
$ splunk-create

Get Started With Generated Packages

After running @splunk/create, run yarn setup inside the created directory to install the dependencies required to manage the project. After this step, the following tasks will be available:

• start Run the start task for each project (see below)
• build Create a production bundle for all projects
• test Run unit tests for each project
• lint Run JS and CSS linters for each project
• format Run prettier to auto-format *.js, *.jsx and *.css files. This command overwrites files without asking.
• format:verify Same as above but will ask to overwrite files.

Running yarn setup once is required to enable all other tasks. The command might take a few minutes to finish.

If you chose to generate a Splunk application, navigate to its directory in the packages subfolder, and run yarn run link:app to establish a link between your Splunk Enterprise installation and your project.

Note: This requires $SPLUNK_HOME to be set, read more here

A Word on yarn start

yarn start has different meanings for different types of packages.

For components

The most common use case for development is to use a component inside a Splunk application, start for components will compile the component and watch for changes.

For Splunk apps

start for Splunk applications will compile and watch application pages. If Create is used to generate a component and a Splunk application, executing yarn start triggers recompilation for both component and app. Changes will be visible in your Splunk Enterprise environment after a reload.

For changes to be visible on refresh, browser caching needs to be disabled, and asset caching needs to be disabled via web.conf

js_no_cache = true
js_logger_mode = Firebug
cacheEntriesLimit = 0
cacheBytesLimit = 0

More information on web.conf options can be reviewed here.

Additional component package tasks

All of the generated packages contain build, lint, and test tasks. In addition to the start command explained above, the following tasks are available for components:

• start:demo Standalone demo mode: start a web server for debugging the component (in watch mode)
• start:app Splunk app demo mode: compile demo as app page (in watch mode)
• link:app Creates a symlink to the demo app

A component's standalone demo and Splunk app demo modes are valuable tools. Using them ensures the component works in an encapsulated way, without outside dependencies and fewer moving parts.

How to add Storybook to existing components

When selecting the option to generate Storybook files for your component(s) make sure you are in the component package directory. Create will ask you to overwrite your component's package.json file – this is just Yeoman updating the dependencies.

Project architecture

Entry point

src/CreateGenerator.js is the main entry point for development. Depending on user input it calls the respective sub-generators.

bin/splunk-create is the main entry point for users interacting with Create. This file sets up a Yeoman environment and forwards to src/CreateGenerator. This allows users to run the package without having to install Yeoman globally.

Package templates

The templates directory houses all of the skeleton projects used by our generators These are bundles of files that the the generator applies rename/replace transformations to, for example ComponentName to MyComponent. The bundles are standalone - if copied, they yield working components.

Updating package dependencies

To update package dependencies, open one of the package.json files in our templates directory and add, remove, and or update a dependency.

🚨 Do make sure that dependency names and versions match what is available via NPM and Artifactory. Any errors here are difficult to test for and can lead to a poor user experience.

Developing for Create

Building and testing

Step 1

cd into packages/create and create a temporary directory with mkdir dirname. Make sure not to check this folder into source control.

Step 2

For active development you will want to open two additional terminal instances and run the following:

In terminal 1: yarn build --watch In terminal 2: yarn test --watch

Note: If you only wish to check a local build, simply run yarn build and or yarn test in sequence without the --watch flags

Step 3

cd into your newly created directory and run the following command:

$ node ../bin/splunk-create

This will run the built project and you should now be able to verify your changes.

Cross platform support

Certain package.json commands in our generated projects require a cross-platform shell script to run on Windows, OSX, and other unix based systems.

See bin/build.js in one of the template directories for examples of this in action. Some common use cases are symlinking, or getting pre-set environment variables.

Updates and subsequent runs

Yeoman is intelligent enough to not blindly overwrite existing files. It generates all output in memory first, and if it encounters conflicts when writing the results, it asks the user how to resolve each conflict. Existing files that aren't generated anymore are not deleted from the file system.

Yeoman resources

• Interacting with the user
• Working with the file system
• Working with yeoman-environment
• Full API Guide for Yeoman 4.x.