@splunk/create

@splunk/create

This package contains Yeoman generators to scaffold minimal Splunk UI React components and applications. Included are build tools, code quality presets, unit tests, and more. The package can also initialize a Lerna-based multirepo project for convenient package management.

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.

How to run Create

For users – using a published version of this package

• Install: npm install -g @splunk/create.
• Create a project directory: mkdir MyProject && cd MyProject.
• Run: splunk-create.

For Create developers – from inside the package

• Build: yarn run build.
• Create a temporary directory: mkdir MyProject && cd MyProject.
• Run: ../bin/splunk-create.

Mode of operation

Create generates components and applications as part of a monorepo, a single repository that contains multiple packages. A monorepo is managed internally by 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 adds generated projects to it.

How to get started with the generated packages

After running the generator, call yarn run setup 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 won't.

Running yarn run 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 (requires $SPLUNK_HOME to be set) and your project.

yarn run start has different meanings for different types of packages. Since the most common use case for development is to use a component inside a Splunk application, start for components will compile and watch a bundle intended to be used in combination with a consuming package. start for Splunk applications will compile and watch application pages. If Create is used to generate a component and a Splunk application, executing yarn run start retriggers recompilation for both component and app. Changes will be immediately visible in your Splunk Enterprise environment after a reload. Note: browser caching should be disabled.

If you chose to generate Storybook, it asks to overwrite your package.json file. This is just adding dependencies. Also, make sure you are in the component package directory.

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 webserver 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.

Internal package details

Run unit tests

• Run: yarn run test

This executes the generator unit tests. Each test operates on the output of a generator run in a temporary directory, using Yeoman helpers and assertions to do so.

Package structure

• bin/splunk-create - sets up Yeoman and forwards to the actual generator. This allows users to run the package without having to install Yeoman globally.
• src – Generator source and unit tests. CreateGenerator is the main entry point, depending on user input it calls the respective sub-generators.
• templates – The skeleton projects used by the generators. These are bundles of files that the generator applies rename/replace transformations to, for example ComponentName to MyComponent. The bundles are standalone - if copied, they yield working components.

Updates / repeatedly running the generators

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 (overwrite/skip/diff/…).

Existing files that aren't generated anymore are not deleted from the file system.