Skip to main content

Environment Setup

Play+ is an enterprise-grade design system delivered via a secure, private registry. This ensures high security, robust version control, and seamless integration within your internal infrastructure.

This guide is divided into two parts:

  • Enterprise Setup: A one-time server configuration performed by system administrators.
  • Developer Setup: A self-service process for developers to configure their local environments.

1. Enterprise Setup (One-Time by Admin)​

To make Play+ available to your development teams, your administrator must deploy the private registry using a pre-configured Docker image maintained by Ascendion.

This section explains how to securely host the Play+ registry and make it accessible across your organization.

Deployment Requirements​

  • Docker must be installed and running on the server.
  • Environment variables for your identity provider (IdP), such as Azure AD or Okta.
  • Access to the ascendion/playplus-registry Docker image.

Deploying the Private Registry​

Run the following command, replacing the environment variables with your own values based on your SSO configuration.

docker run -d -p 4873:4873 \
  -e "VERDACCIO_OAUTH_CLIENT_ID=your-client-id" \
  -e "VERDACCIO_OAUTH_CLIENT_SECRET=your-client-secret" \
  -e "VERDACCIO_OAUTH_DISCOVERY_URL=https://login.microsoftonline.com/your-tenant-id/v2.0/.well-known/openid-configuration" \
  ascendion/playplus-registry:latest

This command starts a private npm registry, configured to serve all @playplus/* packages. Once running, your administrator should share the registry URL (e.g., https://play.contoso.com) with your development teams.

What’s Inside the Docker Image​

The ascendion/playplus-registry Docker image is designed to be secure, self-contained, and ready for immediate use in enterprise environments. It includes:

  • Verdaccio: A lightweight, open-source private npm registry.
  • OAuth2 Authentication: Pre-configured for integration with identity providers such as Azure AD, Okta, and others, using the verdaccio-auth-oauth2 plugin.
  • Play+ Packages: Hosts all core packages including the component library, CLI tools, token system, and scaffolding templates.
  • Secure Defaults: Includes sensible enterprise-ready defaults such as HTTPS support and strict access control.

For more detailed configuration options or support for non-Azure identity providers, refer to internal documentation or contact the Play+ support team.

2. Developer Setup (Self-Service by Developers)​

Once the private registry is deployed, developers can begin configuring their local machines to use Play+. The setup process consists of two straightforward steps.

Step 1: Prepare Your Local Environment​

Before you connect to the Play+ registry, ensure your development environment includes the following tools:

Node.js and npm​

Play+ is built on modern JavaScript standards and depends on Node.js and npm.

  • Download the latest LTS version of Node.js from the official site.
  • This also includes npm, the Node Package Manager.

To verify installation, run:

node --version
npm --version

npx (npm Package Runner)​

Our setup tool uses npx, which comes bundled with npm version 5.2 or later. It allows you to execute packages without globally installing them.

Verify npx by running:

npx --version

Git is strongly recommended for version control. You can install it from git-scm.com, or use GUI tools like GitHub Desktop.

Verify Git with:

git --version

Code Editor​

We recommend using Visual Studio Code for the best experience. The Play+ VS Code Extension is tailored for this editor and provides autocompletion, token lookup, and enhanced editing support.

Terminal​

Use your system’s native terminal:

  • Windows: Command Prompt or PowerShell
  • macOS: Terminal.app
  • Linux: Any standard shell (e.g., bash, zsh)

Step 2: Connect to the Play+ Registry​

Once your environment is ready, you can connect to your organization’s private Play+ registry with a single setup command.

Running the Setup Script​

Run the following command in your terminal, replacing the registry URL with the one provided by your administrator:

npx @playplus/setup --registry=https://play.contoso.com

This script performs the following actions:

  1. Configures .npmrc Adds the appropriate registry settings for the @playplus namespace, so npm knows where to fetch Play+ packages.

  2. Authenticates with SSO Triggers an npm login flow, opening a browser window where you sign in using your company’s identity provider.

  3. Installs the Play+ CLI Installs or updates @playplus/cli globally so you can easily scaffold projects, preview components, and run development workflows.

  4. Validates Access Confirms that your credentials are correct and that you can pull packages from the registry without issues.

After the script completes, your machine is fully configured to create and manage Play+ applications.

Licensing and Usage Terms​

Play+ is licensed under an Enterprise License and is the exclusive intellectual property of Ascendion. Use of the Play+ system, including all source code, tools, and distribution packages, is subject to the license agreements of Ascendion.

You are authorized to:

  • Use Play+ within the scope of approved projects
  • Customize and extend components for internal use
  • Integrate Play+ with private repositories and pipelines

You are not authorized to:

  • Redistribute Play+ packages externally
  • Publish modified versions outside approved environments
  • Share registry credentials with third parties

For compliance and legal guidance, please consult your team’s designated legal or procurement contact.

Additional Resources​

  • For Admins: Internal docs on configuring Okta or non-Azure IdPs
  • For Developers: CLI usage, starter templates, and theming guides
  • Support: Reach out via your company’s Play+ support Slack channel or internal helpdesk

Once set up, you’ll be ready to develop with a system that brings design and engineering into joyful alignment. Welcome to Play+.