UI Scaffolding Workflow
The AYX Plugin CLI generates a starter front end for your plugin, and you customize it. If your plugin needs a configuration panel with text boxes, dropdowns, sliders, or other controls, the generated user interface gives you the starting structure.
What UI Scaffolding Is
UI scaffolding is the starter front-end structure for a plugin. It gives you a place to build the configuration panel and connect it to the back-end logic of your plugin. The scaffold isn’t the finished interface. It’s the starting point for your front-end work.
The generated user interface usually includes these items:
A front-end project structure.
Starter files for the configuration panel.
The dependency setup that front-end development needs.
The code that reads and updates the configuration values of the plugin.
Before You Start
You need an SDK workspace and the AYX Plugin CLI. To install the CLI and create a workspace, go to the AYX Plugin CLI page.
You also need Node.js 24 LTS and npm. The CLI and the front-end project use them to generate and build the user interface.
Generate the Scaffold
The CLI generates the user interface in two ways:
Automatically, when you run
create-ayx-plugin.On request, when you run
generate-ui.
When you create a plugin and don’t skip user interface generation, the CLI creates the scaffold for you.
To force user interface generation when you run the CLI unattended, add --no-omit-ui to create-ayx-plugin. To skip it, add --omit-ui.
Generate or Refresh the Scaffold with generate-ui
Use generate-ui when you need to create or refresh the scaffold for a plugin that already exists. Use it when the template changes, or when you need to regenerate the starter files for an existing plugin.
ayx_plugin_cli generate-ui
The command accepts these flags:
--tool-name: A list of plugin names to generate the user interface for. If you omit it, the command runs across all plugins in the workspace.--omit-ui: Skip UI generation during plugin creation.--no-omit-ui: Ensure the UI scaffold is generated during plugin creation, which is useful for automation.
What the Generated User Interface Includes
The generated files provide entry points for front-end development. The scaffold uses these libraries:
React Comms (
react-comms) keeps the state of the user interface in sync with the plugin model.Alteryx Components (
alteryx-ui) is the component library that the scaffold uses.
These libraries carry data between the user interface and the plugin back end. The scaffold gives you the places where you read and update configuration values.
Scaffold Layout
The CLI creates the generated files in the ui/<ToolName>/src/ folder of the plugin. The component names can vary by template version. The scaffold generally gives you these items:
An entry component for the plugin user interface.
One or more starter components or helpers.
A configuration model or a defaults object.
Code that reads the current model and updates it through the UI SDK context.
If a command output or an older example shows a different path, rely on the project structure that the CLI generated in your workspace.
Regenerate the Scaffold
Run generate-ui to refresh the scaffold when the template changes, or when you need to recreate the starter files for an existing plugin.
When you customize the generated interface, keep your own components and logic in separate files. This makes it easier to regenerate the scaffold later without losing your work. If you aren’t sure whether a file is managed by the scaffold or written by you, check the generated project structure before you replace it.
When to Skip User Interface Generation
Use --omit-ui when any of these statements is true:
The plugin doesn’t need a custom configuration panel.
The plugin is back-end only.
You want to defer the front-end work.
For a new plugin, it’s normal to start with --omit-ui when the back-end behavior is your first focus. You add the user interface later.
After the Scaffold Is Created
After generation, you can do several things with the user interface:
Customize it with additional controls.
Connect it to the plugin's configuration values.
Adjust it for layout or component structure.
Build and test it with the front-end project commands.
For scaffold-specific work, the key goal is to establish the front-end entry point, the state/configuration bridge, and the package structure that future UI work will extend.
Add a Simple Component
After the scaffold exists, you add front-end components as you do in most React projects. You create the component, render it from the main view, and connect it to the configuration of the plugin.
A text input that captures a label or a parameter value is a simple example.
Create a component file, for example
TextValueInput.tsx.Define a component that accepts a value and a change handler.
Render the component from the main UI view.
Update the component state when a user types in the field.
Pass the updated value back to the plugin configuration or to other user interface state.
Here is an example component:
type TextValueInputProps = {
value: string;
onChange: (nextValue: string) => void;
};
export function TextValueInput({ value, onChange }: TextValueInputProps) {
return (
<label>
Tool label
<input
type="text"
value={value}
onChange={(event) => onChange(event.target.value)}
/>
</label>
);
}
Most front-end controls have the same shape:
A value passes into the component.
The component displays that value.
When a user edits it, the component calls the
onChangecallback.The parent view stores the updated value.
Read Input and Write Data Back
Front-end components exchange data in two directions:
Data into the component: The parent view passes the current value into the component through props. The component renders the current state.
Data out of the component: The component calls a callback when the user changes the value. The parent view stores the updated state and can write it back to the plugin configuration or to other shared state.
In a plugin user interface, this exchange is the bridge between the visible form and the configuration that the back end uses later. For example, a text field reads a value from the current configuration, displays it, and sends the edited value back when the user types. A dropdown works the same way for a selected option.