Skip to main content

Portal Studio

Portal Studio is a local development system that connects your workspace to an existing Portal instance, enabling you to develop both frontend and backend plugins and modules directly in Portal with hot reloading. Studio Mode lets you iterate on features in-place without requiring a full local Backstage setup.

Portal Studio allows you to:

  • Connect your local workspace to Portal - Develop plugins against your actual Portal instance
  • Develop frontend and backend features - Support for plugins, modules, and extensions
  • See changes immediately - Hot module reloading for rapid iteration
  • Test with real data - Work with your actual configuration, catalog, and integrations
  • Selective loading - Load only the plugins you're working on for faster iteration

Prerequisites​

Portal Studio prerequisites are similar to the Backstage ones. Most importantly:

  • Node.js 22 (recommended)
  • Yarn installed (npm i -g yarn)
  • React Developer Tools browser extension installed (for React Refresh to work correctly)

Any plugins or features developed using Portal Studio must support Backstage's new backend and frontend systems.

Getting Started with Portal Studio​

There are two ways to use Portal Studio:

  1. Create a new Studio workspace - Start fresh with a minimal workspace configured for your Portal instance
  2. Use an existing workspace - Add Studio to an existing Backstage or plugin repository

Option 1: Create a New Studio Workspace​

The studio init command scaffolds a minimal workspace configured for your Portal instance:

# Create and navigate to a new directory
mkdir my-portal-plugins
cd my-portal-plugins

# Initialize Portal Studio workspace
npx @spotify/portal-cli@latest studio init --instance <your-instance-name>

Options:

  • --instance - Name (e.g., acme) or full URL (e.g., https://portal.acme.org) of your Portal instance
  • --skip-install - Skip running yarn install after templating

When prompted for a Portal instance, you can provide either:

  • Instance name: acme
  • Full URL: https://portal.acme.org

After initialization completes, your workspace is ready with configuration pre-filled for your instance.

Next steps:

# Create a new plugin
yarn new

# Start Portal Studio
yarn start

Option 2: Use an Existing Workspace​

Portal Studio can be used with any existing Backstage workspace, such as the backstage-plugins repository.

# Navigate to your workspace
cd my-backstage-workspace

# Start Studio using npx
npx @spotify/portal-cli@latest studio start --instance <your-instance-name>

Selective Loading​

To avoid loading all packages in a large workspace, you can specify which packages to load:

# Load specific directory
npx @spotify/portal-cli@latest studio start --instance acme plugins/rbac

# Load with glob patterns
npx @spotify/portal-cli@latest studio start --instance acme plugins/*

# Load by plugin ID
npx @spotify/portal-cli@latest studio start --instance acme --plugin soundcheck
tip

For large workspaces, selective loading significantly improves startup time and development experience.

Using Portal Studio​

Starting Studio Mode​

When you run yarn start (or studio start), the CLI will:

  1. Detect your local features (plugins, modules, extensions)
  2. Start the Studio dev server
  3. If you include backend packages, start a local Studio backend
  4. Print a Bootstrap URL

The Bootstrap URL looks like: https://your-instance.spotifyportal.com/?portal-dev-mode=...

Open this URL in your browser to activate Studio Mode in Portal.

Studio Mode Features​

While in Studio Mode:

  • Hot Reloading - Frontend changes appear immediately in Portal
  • Backend Proxying - API requests to your local backend plugins are automatically redirected
  • Real Data - Test with your actual Portal catalog, configuration, and integrations
  • Browser DevTools - Use standard debugging tools (Console, Network, React DevTools)
note

For React Refresh to work correctly, you must have the React Developer Tools extension installed in your browser.

Creating a New Plugin​

In a Studio workspace, use the standard Backstage command:

yarn new

This launches an interactive prompt to create:

  • Frontend Plugin - UI components, pages, and extensions
  • Backend Plugin - APIs, data processors, and integrations
  • Backend Module - Extensions to existing backend plugins (e.g., catalog providers, Soundcheck collectors)

Developing Your Plugin​

  1. Make changes to your plugin code in your local editor
  2. Save the file
  3. See the changes immediately in Portal (browser will hot reload automatically)
  4. Check the terminal for any build errors or warnings

Backend Development​

If your workspace includes backend packages, Portal Studio will start a local backend server. While in Studio Mode, any requests to endpoints provided by your local backend plugins will be redirected to your local server.

# Example: Start Studio with a backend plugin
npx @spotify/portal-cli@latest studio start --instance acme plugins/my-backend-plugin

Plugin Development Workflow​

Frontend Plugins​

Frontend plugins must use the new frontend system to work with Portal Studio.

Example workflow:

  1. Create a new frontend plugin with yarn new
  2. Develop your components in your local editor
  3. Save changes
  4. See updates immediately in Portal (hot reload)
  5. Test with real Portal data and configuration

Refer to Backstage's frontend plugin guide for development patterns.

Backend Plugins​

Backend plugins must use the new backend system to work with Portal Studio.

Example workflow:

  1. Create a new backend plugin with yarn new
  2. Implement your API endpoints or services
  3. Save changes
  4. Backend server restarts automatically
  5. Test API endpoints against your Portal instance

Refer to Backstage's backend plugin guide for development patterns.

Backend Modules​

Backend modules extend existing plugins (e.g., catalog providers, Soundcheck collectors):

# Create a catalog provider module
yarn new
# > backend-module
# > catalog
# > my-provider

Modules are loaded alongside the plugin they extend and can use the plugin's extension points.

Testing Your Plugin​

Real-time Testing in Portal​

As you develop, you can immediately test your plugin in the actual Portal environment:

  • Frontend features - Navigate to your plugin's pages, interact with UI components
  • Backend APIs - Make API calls from Portal to your local backend
  • Integrations - Test with real catalog entities, configurations, and third-party services
  • Permissions - Verify RBAC policies work correctly

Using Browser DevTools​

Open Chrome/Firefox DevTools (F12 or right-click → Inspect) to access:

  • Console - View logs, errors, and debug output
  • Network - Debug API calls and responses
  • React DevTools - Inspect component state and props
  • Performance - Profile and optimize performance

Running Tests​

You can run unit tests in your local workspace:

# Run tests for all packages
yarn test

# Run tests for specific package
yarn test plugins/my-plugin

# Run tests without watch mode
yarn test --no-watch

Publishing Your Plugin​

When you're ready to publish your plugin to Portal:

  1. Build your plugin:

    yarn workspace @internal/plugin-my-plugin build

  2. Publish to npm registry:

    yarn workspace @internal/plugin-my-plugin npm publish

  3. Install in Portal - Follow the Publishing Plugins guide

See Publishing Plugins for complete details on the publishing process.

Configuring Local Backends​

When running Studio Mode, local backend plugins and services use the standard Backstage configuration system. You can manage secrets, environment-specific settings, and other options using the app-config.local.yaml file or other supported configuration files.

Avoid setting environment variables directly for configuration. Instead, add any required configuration values to your workspace's YAML config files—this allows for better consistency and version control.

Refer to the Backstage configuration documentation for details on structuring and managing configuration for your local backend while using Studio Mode.

Troubleshooting​

Studio URL not working​

  • Ensure the Bootstrap URL is complete and correctly copied
  • Check that your local dev server is running (check terminal output)
  • Try refreshing the Portal page

Changes not appearing​

  • Ensure you have React Developer Tools installed
  • Check the terminal for build errors
  • Try hard refresh (Cmd/Ctrl + Shift + R)
  • Restart the Studio dev server

Backend plugin not proxying​

  • Verify backend packages are included in the studio start command
  • Check terminal output for backend startup errors
  • Ensure your backend plugin exports are correct

Build errors​

# Clear cache and reinstall
yarn clean
rm -rf node_modules
yarn install

# Restart Studio
yarn start

Memory issues with large workspaces​

Use selective loading to reduce memory usage:

# Load only specific plugins
npx @spotify/portal-cli@latest studio start --instance acme --plugin my-plugin

Best Practices​

1. Use version control​

Commit your changes regularly to Git. Portal Studio works with local files, so standard Git workflows apply.

2. Test incrementally​

Test your changes frequently in Studio Mode rather than building large features before testing.

3. Monitor terminal output​

Keep an eye on the terminal for build errors, warnings, and logs from your backend plugins.

4. Use selective loading for large repos​

If working in a large monorepo, load only the packages you need to improve performance.

5. Develop iteratively​

Start with basic functionality and add features incrementally. Studio's hot reloading makes rapid iteration easy.

Advanced Usage​

Multiple Plugins​

Load multiple plugins by specifying multiple paths:

npx @spotify/portal-cli@latest studio start --instance acme \
  plugins/plugin-one \
  plugins/plugin-two

Environment-specific Configuration​

Use different Portal instances for different environments:

# Development
yarn start --instance dev-portal

# Staging
yarn start --instance staging-portal

CLI Reference​

Key commands:

  • studio init - Initialize a new Studio workspace
  • studio start - Start Studio dev server and connect to Portal

Getting Help​

If you encounter issues with Portal Studio:

  1. Review error messages in the terminal
  2. Check browser console for frontend errors
  3. Contact Spotify Support