First Steps

This page will cover the basic workflow for using STRUDEL Kit to build a web UI.

There are three primary steps to using STRUDEL Kit:

1. Build a base app
2. Add Task Flows
3. Customize

Confirm CLI installation

Confirm that you have the strudel-cli installed in your current environment:

strudel --version

Build a base app

The first step to getting started with the STRUDEL Kit is to build a base app using the create-app command.

strudel create-app my-app

This will generate a new directory called my-app with the basic scaffolding for a STRUDEL-powered React app. The name my-app can be replaced with any name you like. It's typical to us all lowercase kebab-case for project names.

The app comes pre-baked with all libraries in the STRUDEL Tech Stack as well as a set of custom components that are used across the app and the Task Flow templates.

Base app files breakdown

my-app
├── public
├── src
│  ├── components # Components that are shared across the app
│  ├── context # State variables and actions shared across the app
│  ├── pages # Task Flows and pages that are automatically registered to the app router
│  │  ├── playground
│  │  │  └── index.tsx # Playground component for testing code
│  │  └── index.tsx # Home page component
│  ├── types # TypeScript definitions used across the app
│  ├── utils # Utility functions and hooks used across the app
│  ├── App.tsx # Top-level app component
│  ├── declarations.d.ts
│  ├── index.css # Base CSS styles
│  ├── main.tsx # App entry point
│  ├── router.ts # Auto-generated routes
│  ├── theme.tsx # Full theme configuration
│  └── vite-env.d.ts
├── .eslintrc.cjs
├── .gitignore
├── README.md
├── index.html
├── package.json
├── strudel.config.ts # Base strudel configuration file
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts

Start up your app

Once your app is generated, you can cd into the new directory, install the dependencies, and start the app.

cd my-app
npm install
npm start

Your app should now be running at http://localhost:5173. At this point your app will have a home page at the root path / and a playground page at /playground.

Configure up your app

STRUDEL Kit makes use of a simple configuration file at the root of your app called strudel.config.ts. Here you can set a few basic global options and content items like a site logo, navigation links, and basic theme variables.

strudel.config.ts

/**
 * Configure global options and content for your app.
 */
export const config = {
  title: 'STRUDEL + React + MUI',
  navbar: {
    title: 'My Project',
    logo: 'strudel-logo-icon.png',
    items: [
      {
        label: 'Playground',
        path: '/playground'
      }
    ]
  },
  footer: {
    info: 'Describe your project, place a copyright statement, or credit your funding organizations.',
    image: 'strudel-logo-header.png',
    links: [
      {
        label: 'Playground',
        path: '/playground'
      },
    ]
  }
}

The theme variables available in the config are only the most common theme customizations. You can make even more customizations in src/theme.tsx. See the Theme Customization guide for more info.

Add a Task Flow

After you have your base app up and running, you can add Task Flow templates into your app. Task Flows templates are full UI flows built out as React components that plug directly into your base app. Run the following command from inside the root of your app directory to add a Task Flow called my-taskflow that uses the compare-data Task Flow template:

strudel add-taskflow my-taskflow --template compare-data

This generates a new directory at src/pages/my-taskflow with all the files you need to run the initial Task Flow.

Task Flow files breakdown

my-taskflow
├── _config
│  ├── taskflow.config.ts # Task Flow configuration file
│  └── taskflow.types.ts # Type definitions for the config object
├── _context
│  ├── ContextProvider.tsx # State variables shared across the Task Flow
│  └── actions.ts # Actions shared across the Task Flow
├── _layout.tsx # Layout wrapper for all the Task Flow pages
├── compare.tsx # Compare page component
├── index.tsx # Initial page component
└── new.tsx # New page component

You can add one Task Flow after the other or add them progressively as you are ready to start working with them in your app. The name you give your Task Flow maps to the directory name so make sure that each Task Flow has a unique name. You can pass any of the available templates to the --template option. Here's what it would look like to add another Task Flow using the explore-data template:

strudel add-taskflow my-other-taskflow --template explore-data

Each Task Flow is registered as a URL route in your app as soon as it's added. For example, after adding the above Task Flows, you can now go to http://localhost:5173/my-taskflow and http://localhost:5173/my-other-taskflow to see your templates in action.

Customize your Task Flow

Similar to the base app, each Task Flow comes with its own configuration file. You can find the configuration file in _config/taskflow.config.ts inside the newly created directory for your Task Flow. Here you can start customizing the content in your Task Flow and connecting your own data sources. Check out the Task Flows section for more information about how to configure each Task Flow.

If you'd like to customize the Task Flow beyond what you can do with the configuration file, you have full reign to edit the components in the template. Check out these helpful guides on customizing Task Flow components:

Customize Your Task Flow

Combining Sections

Connecting Task Flows