Authentication Guide
You purchased a license—now let's get your packages installing locally and deploying seamlessly to Vercel, GitHub Actions, and beyond.
Get started with Three Blocks by subscribing to access private packages.
Set up Three Blocks packages on your development machine
Configure environment variables for production builds
Fix common 401 errors and authentication problems
Two ways to authenticate with Three Blocks packages. We recommend the automatic method for production and CI/CD workflows.
Authentication runs automatically before every install. Perfect for teams and deployments.
Benefits:
Run a CLI command once to authenticate. Best for local development and quick testing.
Benefits:
Limitations:
Set up once, works everywhere. This method uses a preinstall hook to authenticate automatically before every package install.
Create a .npmrc file in your project root. The registry URL depends on your plan.
@three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/@three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/pro/✅ Safe to commit - This file contains no secrets. Commit it to git.
Add this to your package.json. It runs the authentication CLI automatically before every install.
{
"scripts": {
"preinstall": "npx -y three-blocks-login@latest"
}
}💡 Package manager alternatives:
pnpm: "preinstall": "pnpm dlx three-blocks-login@latest"
yarn: "preinstall": "npx -y three-blocks-login@latest"
bun: "preinstall": "bunx three-blocks-login@latest"
Set your license key as an environment variable. Your key starts with tb_ and can be found in your account dashboard.
For local development, create a .env.local file:
THREE_BLOCKS_SECRET_KEY=tb_your-license-key-hereOr export in your terminal session:
export THREE_BLOCKS_SECRET_KEY="tb_your-license-key-here"⚠️ Never commit secrets - Add .env.local to your .gitignore.
Now just install packages normally. The preinstall hook handles authentication automatically.
pnpm install @three-blocks/core🎉
That's it! You're all set.
The preinstall hook will run before every install, keeping your authentication fresh.
Run the authentication CLI when you need it. The CLI will prompt for your license key interactively.
Run the CLI and it will prompt you for your license key interactively. It then configures your .npmrc automatically.
pnpm dlx three-blocks-login
💡 The CLI will ask for your license key if THREE_BLOCKS_SECRET_KEY is not set. It then writes both the registry URL and auth token to your .npmrc.
If you prefer to skip the interactive prompt, export your key first:
export THREE_BLOCKS_SECRET_KEY="tb_your-license-key-here"
pnpm dlx three-blocks-loginNow you can install Three Blocks packages normally.
pnpm install @three-blocks/core✨
Done!
You're authenticated and ready to install packages.
Auth tokens expire after 12 hours. When you see authentication errors, just run pnpm dlx three-blocks-login again.
This is why we recommend the automatic method for production—it refreshes tokens automatically.
Three Blocks packages are hosted on AWS CodeArtifact, a private npm registry. When you install packages, npm/pnpm needs to authenticate with this registry.
pnpm install preinstall script runs three-blocks-login three-blocks-login sends your license key to our broker service .npmrc file 💡 Why the preinstall script? Tokens expire after 12 hours for security. The preinstall script ensures you always have a fresh token before installing packages, so you never hit authentication errors.
Choose your deployment platform for detailed setup instructions:
Deploy with Vercel's platform. This is the most common deployment platform.
View guide →Configure CI/CD pipelines with GitHub Actions.
View guide →Deploy with Netlify's edge network.
View guide →Railway, Render, and generic CI/CD setups.
View guide →This is where most users deploy. We know auth setup can be frustrating, so we've broken it down step-by-step.
.npmrc file is committed to git
Go to your project settings in Vercel and add the THREE_BLOCKS_SECRET_KEY environment variable.
1. Open your project in Vercel
2. Go to Settings → Environment Variables
3. Add a new variable:
Key:
THREE_BLOCKS_SECRET_KEY Value:
tb_your-license-key ⚠️ Important: Enable this variable for all environments (Production, Preview, Development)
Vercel needs the .npmrc file to know where to find Three Blocks packages. Make sure it's in your git repository.
git status
# .npmrc should NOT appear in untracked files
git add .npmrc
git commit -m "Add npmrc for Three Blocks registry"
git pushPush a new commit or trigger a redeploy from the Vercel dashboard. Your build should now succeed!
✅ You should see: Installing dependencies... followed by successful installation of @three-blocks/core
If your Vercel build fails with authentication errors, check:
THREE_BLOCKS_SECRET_KEY set in Vercel environment variables? .npmrc file committed to your repository? Configure CI/CD pipelines to build and test with Three Blocks packages.
Go to your GitHub repository settings and add your license key as a secret:
THREE_BLOCKS_SECRET_KEYtb_)Add the environment variable to your workflow file:
name: CI
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install pnpm
uses: pnpm/action-setup@v2
with:
version: 8
- name: Install dependencies
env:
THREE_BLOCKS_SECRET_KEY: ${{ secrets.THREE_BLOCKS_SECRET_KEY }}
run: pnpm install
- name: Build
run: pnpm build
- name: Test
run: pnpm test💡 Key point: The env section passes the secret to the install step where the preinstall script can access it.
Deploy with Netlify's edge network and CDN.
Netlify setup is similar to Vercel. The key is adding your license key as an environment variable.
THREE_BLOCKS_SECRET_KEY✅ That's it! Your builds should now have access to Three Blocks packages.
Railway, Render, or any platform with environment variables support.
For any CI/CD or deployment platform, follow these universal steps:
Make sure your .npmrc file with the registry URL is committed to git
Add THREE_BLOCKS_SECRET_KEY=tb_your-key to your platform's environment variables
Ensure your package.json has the preinstall script
Trigger a build—the preinstall script will authenticate before installing packages
npm/pnpm says "Unable to authenticate" when installing packages
Problem: License key not set
The THREE_BLOCKS_SECRET_KEY environment variable is missing or empty.
Solution: Set the environment variable in your terminal or .env.local file
Problem: Invalid license key
Your license key is incorrect, expired, or your subscription is inactive.
Solution: Verify your license key in your account dashboard and check your subscription status
Problem: Token expired
npm tokens expire after 12 hours. Your cached token may be stale.
Solution: Run pnpm dlx three-blocks-login@latest manually to refresh the token
Problem: .npmrc missing registry URL
Your .npmrc doesn't have the Three Blocks registry configuration.
Solution: Add the registry URL to your .npmrc:
@three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/
npm/pnpm says @three-blocks/core doesn't exist
Cause
npm/pnpm is looking for the package on the public npm registry instead of the Three Blocks private registry.
Solution
Make sure your .npmrc has the correct registry configuration for your plan:
Indie Plan:
@three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/
Pro / Company Plan:
@three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/pro/
Works locally but fails on Vercel
Check these items in order:
1. Environment variable set?
Go to Vercel project settings → Environment Variables → Verify THREE_BLOCKS_SECRET_KEY exists and is enabled for your environment
2. .npmrc committed?
Run git ls-files .npmrc - if it returns nothing, your .npmrc is not committed
3. Preinstall script present?
Check package.json has the preinstall script
4. Check build logs
Look for "preinstall" in the logs - you should see three-blocks-login running and outputting "✓ Authentication successful"
.npmrc with registry URL only (no tokens) package.json with preinstall script .npmrc with auth tokens .env.local with license keys tb_ license key We're here to help! Reach out through any of these channels: