Migration Guide: @studs/react to @strongtie/design-system

📋 Overview

This guide will help you migrate from the deprecated @studs/react package to the new @strongtie/design-system package.

What’s Changing?

Item	Old (@studs/react)	New (@strongtie/design-system)
Package Name	`@studs/react`	`@strongtie/design-system`
Registry	npm (public)	GitHub Package Manager (enterprise)
Version	3.1.2	1.0.0
Scope	`@studs`	`@strongtie`

Why the Change?

The @studs/react package has been rebranded as @strongtie/design-system to:

Better align with Simpson Strong-Tie’s enterprise infrastructure
Consolidate under a unified enterprise scope
Provide enhanced security through private GitHub Package Manager
Signal a new chapter in the design system’s evolution

⚠️ Breaking Changes

Package Name Change

All imports must be updated from @studs/react to @strongtie/design-system.

Version Reset

The new package starts at v1.0.0. While the API remains largely the same, the version number reflects the new package identity.

🚀 Migration Steps

Step 1: Set Up GitHub Package Manager Authentication

Before installing the new package, you need to authenticate with GitHub Package Manager.

1.1 Generate a GitHub Personal Access Token (PAT)

Go to GitHub Settings > Developer Settings > Personal Access Tokens
Click “Generate new token (classic)”
Give it a descriptive name (e.g., “NPM Package Access”)
Select the following scopes:
- ✅ read:packages - Required for installing packages
- ✅ write:packages - Optional, only if you need to publish
Click “Generate token” and copy the token
Click Configure SSO
Select your organization and click “Authorize”

⚠️ Important: Store this token securely - you won’t be able to see it again!

1.2 Configure NPM to Use GitHub Package Manager

Create or update your .npmrc file in your project root or home directory:

# Project-level .npmrc (recommended)
echo "@strongtie:registry=https://npm.pkg.github.com" >> .npmrc

# Or home directory .npmrc for global access
echo "@strongtie:registry=https://npm.pkg.github.com" >> ~/.npmrc

1.3 Authenticate with Your Token

npm login --scope=@strongtie --registry=https://npm.pkg.github.com

When prompted:

Username: Your GitHub username
Password: Your Personal Access Token (PAT)
Email: Your GitHub email address

Alternative: Using .npmrc file directly

# Add to your .npmrc
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

⚠️ Security Note:

Never commit .npmrc files containing tokens to version control
Add .npmrc to your .gitignore if it contains sensitive data
Use environment variables in CI/CD pipelines

Step 2: Update Your Dependencies

2.1 Remove the Old Package

npm uninstall @studs/react
# or
yarn remove @studs/react
# or
pnpm remove @studs/react

2.2 Install the New Package

npm install @strongtie/design-system
# or
yarn add @strongtie/design-system
# or
pnpm add @strongtie/design-system

2.3 Update package.json

Your package.json should now look like this:

{
  "dependencies": {
    "@strongtie/design-system": "^1.0.0"
  }
}

Step 3: Update Your Imports

You’ll need to update all component imports throughout your codebase.

Before (❌ Old):

import { Button } from "@studs/react/button";
import { Card, CardContent } from "@studs/react/card";
import { Input } from "@studs/react/input";
import "@studs/react/styles";

After (✅ New):

import { Button } from "@strongtie/design-system/button";
import { Card, CardContent } from "@strongtie/design-system/card";
import { Input } from "@strongtie/design-system/input";
import "@strongtie/design-system/styles";

Automated Find & Replace

Use your IDE’s find-and-replace feature (with regex if needed): Find: @studs/react Replace: @strongtie/design-system Or use command-line tools:

# Using sed (macOS/Linux)
find src -type f -name "*.tsx" -o -name "*.ts" -o -name "*.jsx" -o -name "*.js" | \
  xargs sed -i '' 's/@studs\/react/@strongtie\/design-system/g'

# Using PowerShell (Windows)
Get-ChildItem -Path src -Recurse -Include *.tsx,*.ts,*.jsx,*.js |
  ForEach-Object {
    (Get-Content $_.FullName) -replace '@studs/react', '@strongtie/design-system' |
    Set-Content $_.FullName
  }

Step 4: Update CSS/Style Imports

If you’re importing styles directly, update those imports as well:

Before (❌ Old):

import "@studs/react/styles";

@import "@studs/react/styles";

After (✅ New):

import "@strongtie/design-system/styles";

@import "@strongtie/design-system/styles";

Step 5: Verify Your Application

After making the changes:

Clear your build cache:
```
rm -rf node_modules/.cache
rm -rf dist
```

Reinstall dependencies:

npm install
# or
yarn install
# or
pnpm install

Run your tests:
```
npm test
```
Start your development server:
```
npm run dev
```
Build your application:
```
npm run build
```

🔍 Component API Compatibility

Good news! The component APIs remain 100% compatible. All props, methods, and behaviors work exactly as before.

Available Components

All 48+ components from @studs/react are available in @strongtie/design-system:

✅ Accordion
✅ Alert
✅ Alert Dialog
✅ Avatar
✅ Badge
✅ Breadcrumb
✅ Button
✅ Calendar
✅ Card
✅ Carousel
✅ Checkbox
✅ Collapsible
✅ Combobox
✅ Context Menu
✅ Date Picker
✅ Dialog
✅ Drawer
✅ Dropdown Menu
✅ Hover Card
✅ Icon
✅ Input
✅ Label
✅ Menubar
✅ Multi Select
✅ Navigation Menu
✅ Pagination
✅ Popover
✅ Progress
✅ Radio Group
✅ Scroll Area
✅ Select
✅ Separator
✅ Sheet
✅ Sidebar
✅ Skeleton
✅ Slider
✅ Switch
✅ Tab Nav
✅ Table
✅ Tabs
✅ Textarea
✅ Toaster
✅ Toggle
✅ Toggle Group
✅ Tooltip
✅ Tree

No Code Changes Required

Once you’ve updated the package name and imports, your existing code will work without modifications:

// This works exactly the same in both packages
import { Button } from "@strongtie/design-system/button";

function MyComponent() {
  return (
    <Button variant="primary" size="lg" onClick={handleClick}>
      Click Me
    </Button>
  );
}

🔧 CI/CD Configuration

GitHub Actions

Add the following to your workflow file:

name: Build and Deploy

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "18"
          registry-url: "https://npm.pkg.github.com"
          scope: "@strongtie"

      - name: Configure npm
        run: |
          echo "@strongtie:registry=https://npm.pkg.github.com" >> .npmrc
          echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" >> .npmrc

      - name: Install dependencies
        run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Build
        run: npm run build

GitLab CI

before_script:
  - echo "@strongtie:registry=https://npm.pkg.github.com" >> .npmrc
  - echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc

build:
  script:
    - npm ci
    - npm run build
  variables:
    GITHUB_TOKEN: ${GITHUB_PAT}

Azure DevOps

steps:
  - task: npmAuthenticate@0
    inputs:
      workingFile: .npmrc
      customEndpoint: "GitHub"

  - script: |
      echo "@strongtie:registry=https://npm.pkg.github.com" >> .npmrc
    displayName: "Configure npm"

  - script: npm ci
    displayName: "Install dependencies"

🐛 Troubleshooting

Issue: “Unable to authenticate”

Problem: Getting 401 Unauthorized errors when installing. Solution:

Verify your GitHub token has read:packages scope
Check that your .npmrc is configured correctly
Ensure you’re using the correct token (not expired)

Try logging in again:

npm login --scope=@strongtie --registry=https://npm.pkg.github.com

Issue: “Package not found”

Problem: npm can’t find @strongtie/design-system. Solution:

Verify the registry is set correctly:
```
npm config get @strongtie:registry
```
Should return: https://npm.pkg.github.com
Check that the package has been published to GitHub Package Manager
Ensure you have access to the repository

Issue: “Module not found” after migration

Problem: Getting import errors after updating package name. Solution:

Clear your build cache:
```
rm -rf node_modules/.cache dist
```

Remove and reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Restart your development server
Check for any missed imports:
```
grep -r "@studs/react" src/
```

Issue: Type errors after migration

Problem: TypeScript can’t find type definitions. Solution:

Clear TypeScript cache:
```
rm -rf node_modules/.cache
```
Restart your TypeScript server (VS Code: Cmd/Ctrl + Shift + P → “Restart TS Server”)
Verify the package is installed correctly:
```
npm list @strongtie/design-system
```

Issue: Styles not loading

Problem: Components render but without styles. Solution:

Verify you’ve updated the styles import:
```
import "@strongtie/design-system/styles";
```
Check that the import is in your main entry file (e.g., main.tsx, App.tsx)
Clear your build cache and restart

📚 Additional Resources

Design System Documentation - Complete design guidelines
Component Library - Interactive Storybook
GitHub Repository - Source code and issues
GitHub Package Manager Docs - Official GitHub documentation

❓ Need Help?

If you encounter any issues during migration:

Check the troubleshooting section above
Search existing issues on GitHub
Create a new issue if your problem isn’t covered
Contact the UX team via Teams

📝 Migration Checklist

Use this checklist to track your migration progress:

🎉 Migration Complete!

Once you’ve completed all the steps above, you’re successfully migrated to @strongtie/design-system! The @studs/react package will continue to work for now but is deprecated and will not receive updates. We strongly recommend completing this migration as soon as possible.

Last Updated: January 2025 Migration Guide Version: 1.0.0

Getting Started

Foundations

Components

Integration Guides

Content

​📋 Overview

​What’s Changing?

​Why the Change?

​⚠️ Breaking Changes

​Package Name Change

​Version Reset

​🚀 Migration Steps

​Step 1: Set Up GitHub Package Manager Authentication

​1.1 Generate a GitHub Personal Access Token (PAT)

​1.2 Configure NPM to Use GitHub Package Manager

​1.3 Authenticate with Your Token

​Step 2: Update Your Dependencies

​2.1 Remove the Old Package

​2.2 Install the New Package

​2.3 Update package.json

​Step 3: Update Your Imports

​Before (❌ Old):

​After (✅ New):

​Automated Find & Replace

​Step 4: Update CSS/Style Imports

​Before (❌ Old):

​After (✅ New):

​Step 5: Verify Your Application

​🔍 Component API Compatibility

​Available Components

​No Code Changes Required

​🔧 CI/CD Configuration

​GitHub Actions

​GitLab CI

​Azure DevOps

​🐛 Troubleshooting

​Issue: “Unable to authenticate”

​Issue: “Package not found”

​Issue: “Module not found” after migration

​Issue: Type errors after migration

​Issue: Styles not loading

​📚 Additional Resources

​❓ Need Help?

​📝 Migration Checklist

​🎉 Migration Complete!

📋 Overview

What’s Changing?

Why the Change?

⚠️ Breaking Changes

Package Name Change

Version Reset

🚀 Migration Steps

Step 1: Set Up GitHub Package Manager Authentication

1.1 Generate a GitHub Personal Access Token (PAT)

1.2 Configure NPM to Use GitHub Package Manager

1.3 Authenticate with Your Token

Step 2: Update Your Dependencies

2.1 Remove the Old Package

2.2 Install the New Package

2.3 Update package.json

Step 3: Update Your Imports

Before (❌ Old):

After (✅ New):

Automated Find & Replace

Step 4: Update CSS/Style Imports

Before (❌ Old):

After (✅ New):

Step 5: Verify Your Application

🔍 Component API Compatibility

Available Components

No Code Changes Required

🔧 CI/CD Configuration

GitHub Actions

GitLab CI

Azure DevOps

🐛 Troubleshooting

Issue: “Unable to authenticate”

Issue: “Package not found”

Issue: “Module not found” after migration

Issue: Type errors after migration

Issue: Styles not loading

📚 Additional Resources

❓ Need Help?

📝 Migration Checklist

🎉 Migration Complete!