Skip to main content

Documentation Index

Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 24 (recommended)
  • Yarn installed (Run corepack enable to have Node manage and install 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 any of the workspaces in the Community Plugins repository. For example, to use Portal Studio with the Announcements plugin, you can do the following: 
# Navigate to your workspace
cd community-plugins/workspaces/announcements
yarn install

# Start Studio using npx
npx @spotify/portal-cli@latest studio start --instance <your-instance-name>
This will start Portal Studio with all the plugins in the Announcements workspace.
Keep in mind that Community Plugins is a monorepo that contains multiple workspaces. If you already have a Backstage app, you can just run npx @spotify/portal-cli@latest command from the root of your Backstage app to start Portal Studio.

​
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/announcements

# 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 announcements
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)
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