Skip to content

Getting Started with Progress Web Components

Welcome to the Progress Web Components design system! This guide will help you set up and start using PWC components in your React or Angular applications.

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js (version 16 or higher)
  • npm or yarn package manager
  • A code editor (VS Code recommended)

Quick Start

1. Create New Project

Choose your preferred framework to get started:

# Create a new React project with TypeScript
npm create vite@latest my-pwc-app -- --template react-ts

# Navigate to project directory
cd my-pwc-app

# Install dependencies
npm install

# Create a new React project with TypeScript
npx create-react-app my-pwc-app --template typescript

# Navigate to project directory
cd my-pwc-app

# Create a new Angular project
ng new my-pwc-app

# Navigate to project directory
cd my-pwc-app

# Install dependencies
npm install

# Navigate to your existing project directory
cd my-existing-project

# Ensure dependencies are installed
npm install

Need a working example? Review the reference implementations in pwc-react-poc and pwc-angular-poc.

2. Authenticate with Azure Artifacts

All Progress I360 packages are published to a private Azure Artifacts feed. You must authenticate before installing dependencies.

  1. Request access – Submit an Ask Progress ticket for the Progress I360 / PWC feed if you do not already have permissions.
  2. Create a Personal Access Token (PAT) – In Azure DevOps, create a PAT with the Packaging (Read) scope. Store it securely.
  3. Configure .npmrc – Add a project-level or user-level .npmrc that points @progress-i360 to the Azure feed. The canonical template lives in the sample repositories pwc-react-poc and pwc-angular-poc. Update the placeholder values with your username, email, and the base64-encoded PAT:
; .npmrc
@progress-i360:registry=https://pkgs.dev.azure.com/Progress/Progress%20I360/_packaging/pwc/npm/registry/
//pkgs.dev.azure.com/Progress/Progress%20I360/_packaging/pwc/npm/registry/:username=<azure-devops-username>
//pkgs.dev.azure.com/Progress/Progress%20I360/_packaging/pwc/npm/registry/:_password=<base64-pat>
//pkgs.dev.azure.com/Progress/Progress%20I360/_packaging/pwc/npm/registry/:email=<work-email>
//pkgs.dev.azure.com/Progress/Progress%20I360/_packaging/pwc/npm/registry/:always-auth=true
  1. Encode the PAT – Windows PowerShell example:
$pat = Read-Host -AsSecureString "Enter Azure DevOps PAT";
$bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($pat);
$plain = [Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr);
[Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":" + $plain))

Copy the resulting string into _password. Repeat the process whenever you rotate the PAT (tokens expire after 90 days by default).

3. Install PWC Components

With authentication in place, install only the packages you need per framework:

npm install @progress-i360/pwc-react
# or
yarn add @progress-i360/pwc-react

npm install @progress-i360/progress-web-components
# or
yarn add @progress-i360/progress-web-components

npm install @progress-i360/progress-web-components
# or
yarn add @progress-i360/progress-web-components

npm install @progress-i360/progress-web-components
# or
yarn add @progress-i360/progress-web-components

4. Configure Your Project

Set up your project to work with PWC components:

TypeScript Configuration (optional)

If using TypeScript, surface the React wrappers by adding them to tsconfig.json:

{
  "compilerOptions": {
    "types": ["@progress-i360/pwc-react"]
  }
}

Custom Element Declarations

React 19 works directly with web components. Add a progress-web-components.d.ts file or extend your existing global declarations so TypeScript recognizes the custom elements:

// src/progress-web-components.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    "pwc-button": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
      label?: string;
      variant?: string;
    };
    // Add other components as needed.
  }
}

Module Configuration

Add CUSTOM_ELEMENTS_SCHEMA to your app.module.ts:

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  providers: [],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA] // Add this line
})
export class AppModule { }

Bundle Configuration

Ensure your bundler can handle ES modules. For Vite:

// vite.config.js
export default {
  build: {
    target: 'es2020'
  }
}

5. Your First Component

Create your first PWC component:

// src/App.tsx
import { useState } from "react";
import { PwcButton } from "@progress-i360/pwc-react";
import "./App.css";

function App() {
  const [count, setCount] = useState(0);

  const handleClick = () => {
    setCount(prev => prev + 1);
  };

  return (
    <div className="App">
      <h1>My PWC App</h1>
      <p>Button clicked {count} times</p>
      <PwcButton
        variant="primary"
        label="Click me!"
        onPwcClick={handleClick}
      />
    </div>
  );
}

export default App;

Wrap your application with <PwcRoot> once at composition time when you need to configure the asset path or shared providers; avoid nesting it inside every component example.

// src/App.tsx
import { useState } from "react";
import "@progress-i360/progress-web-components/button";
import "./App.css";

function App() {
  const [count, setCount] = useState(0);

  return (
    <div className="App">
      <h1>My PWC App</h1>
      <p>Button clicked {count} times</p>
      <pwc-button
        variant="primary"
        label="Click me!"
        onPwcClick={() => setCount(prev => prev + 1)}
      ></pwc-button>
    </div>
  );
}

export default App;

// src/app/app.component.ts
import "@progress-i360/progress-web-components/button";

@Component({
  selector: "app-root",
  template: `
    <div class="app">
      <h1>My PWC App</h1>
      <p>Button clicked {{ count }} times</p>
      <pwc-button
        variant="primary"
        label="Click me!"
        (pwc-click)="handleClick()"
      ></pwc-button>
    </div>
  `,
  styleUrls: ["./app.component.css"]
})
export class AppComponent {
  count = 0;

  handleClick() {
    this.count++;
  }
}

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My PWC App</title>
</head>
<body>
    <div id="app">
        <h1>My PWC App</h1>
        <p id="counter">Button clicked 0 times</p>
        <pwc-button id="myButton" variant="primary" label="Click me!"></pwc-button>
    </div>
    <script type="module" src="./main.js"></script>
</body>
</html>

```javascript // main.js

import "@progress-i360/progress-web-components/button";

let count = 0;
const button = document.getElementById('myButton');
const counter = document.getElementById('counter');

button.addEventListener('pwc-click', () => { count++; counter.textContent = Button clicked ${count} times; }); ```

6. Start Development

Launch your development server:

npm run dev

npm start

ng serve

# If using Vite
npm run dev

# Or serve static files
npx serve .

Project Structure

Organize your PWC components efficiently:

my-pwc-app/
├── src/
│   ├── components/          # Your custom components
│   │   ├── Layout/
│   │   ├── Forms/
│   │   └── Navigation/
│   ├── pages/              # Application pages
│   ├── styles/             # Global styles
│   └── utils/              # Utility functions
├── public/                 # Static assets
└── package.json

Best Practices

Import Strategy

Import only the components you need to optimize bundle size:

// ✅ Good - Import specific components only
import { PwcButton, PwcInput } from "@progress-i360/pwc-react"; // React < 19
import "@progress-i360/progress-web-components/button"; // React 19+, Angular, Vanilla
import "@progress-i360/progress-web-components/input";

// ❌ Avoid - Importing entire libraries
import "@progress-i360/pwc-react";
import "@progress-i360/progress-web-components";

TypeScript Integration

For better development experience with TypeScript:

// Create types for custom events
interface PWCButtonEvent extends CustomEvent {
  detail: {
    value: string;
  };
}

// Use proper event typing
const handleButtonClick = (event: PWCButtonEvent) => {
  console.log('Button clicked:', event.detail.value);
};

Troubleshooting

Common Issues

Components Not Rendering: - Ensure you've imported the component before using it - Check that CUSTOM_ELEMENTS_SCHEMA is added (Angular) - Verify the component name matches exactly

TypeScript Errors: - Add PWC types to your tsconfig.json (React < 19) or extend JSX intrinsic elements for web components (React 19+) - Use any type temporarily for custom elements if needed

Styling Issues: - Check if CSS custom properties are properly defined - Ensure component styles aren't being overridden

Event Handling: - Use onPwcEventName format for React event props - Use (pwc-event-name) format for Angular event binding

Getting Help

Next Steps

Now that you have PWC components set up, explore:

  1. Component Library - Browse all available components
  2. Design Tokens - Learn about design system tokens
  3. Patterns - Common UI patterns and layouts
  4. Themes - Customize appearance with themes

Ready to build amazing user interfaces with Progress Web Components! 🚀