Skip to main content

​
Prerequisites

Before deploying, make sure you have:
  1. A valid linkapp.config.ts with required manifest fields
  2. A production build in dist/ (or linkapp will build automatically)
  3. Authentication credentials (run npx @linktr.ee/linkapp login first)

​
Authenticate

Log in to Linktree before your first deployment: 
npx @linktr.ee/linkapp login
This opens a browser window for OAuth device flow authentication. Your tokens are stored in ~/.config/linkapp/auth-token.json.

​
Deploy your LinkApp

Deploy to production: 
npm run deploy
Or use the CLI directly: 
npx @linktr.ee/linkapp deploy

​
Deploy to QA

To deploy to the QA environment: 
npx @linktr.ee/linkapp deploy --qa

​
Deployment process

When you run linkapp deploy:
  1. Validates your project and config
  2. Builds the app (if needed)
  3. Uploads to Linktree

​
Deployment flags

FlagDescription
--qaDeploy to QA environment instead of production
--skip-buildSkip building (use existing dist/)
--skip-checksSkip pre-deployment validation
--forceForce deploy even if warnings
Example: 
npx @linktr.ee/linkapp deploy --qa --skip-build

​
After deployment

After a successful deployment, you’ll see: 
✓ Deployed successfully!

Build URL: https://linktr.ee/builds/abc123
Test link: https://linktr.ee/test?app=my-app

Next steps:
  • View your build in the Linktree dashboard
  • Test your LinkApp on a Linktree profile
  • Share the build URL with your team
Use the test link to preview your LinkApp on a real Linktree profile before publishing.

​
Troubleshooting

​
Validation errors

If you see config validation errors: 
Error: Invalid config
  - manifest.title: Required
  - manifest.description: Max 200 characters
  - settings[0].id: Must be alphanumeric
Fix these in your linkapp.config.ts and redeploy.

​
Bundle size warnings

If your bundle exceeds 5MB: 
⚠ Warning: Bundle size is 6.2MB (exceeds 5MB recommended limit)
Consider using dynamic imports, removing unused dependencies, or optimizing images.

​
Authentication errors

If you see 401 Unauthorized: 
npx @linktr.ee/linkapp logout
npx @linktr.ee/linkapp login

​
Build errors

If the build fails during deployment: 
# Build locally to see errors
npx @linktr.ee/linkapp build

# Fix errors, then deploy
npx @linktr.ee/linkapp deploy --skip-build

​
Config schema errors

Check your config against the schema: 
# This will validate during build
npx @linktr.ee/linkapp build

​
Deployment fails

Enable verbose logging: 
DEBUG=linkapp:* npx @linktr.ee/linkapp deploy

​
Multiple environments

You can maintain separate LinkApps for development and production:
linkapp.config.ts
export default {
  manifest: {
    name: process.env.LINKAPP_ENV === "qa" ? "My App QA" : "My App",
    // Generates IDs: "my-app-qa" or "my-app"
  },
  settings: {
    title: process.env.LINKAPP_ENV === "qa" ? "My App (QA)" : "My App",
  },
};
Deploy to QA: 
LINKAPP_ENV=qa npx @linktr.ee/linkapp deploy --qa
Deploy to production: 
LINKAPP_ENV=prod npx @linktr.ee/linkapp deploy

​
CI/CD integration

Deploy from CI/CD pipelines:
.github/workflows/deploy.yml
name: Deploy LinkApp

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install
      - run: npm run build
      - run: npm run deploy
        env:
          LINKTREE_TOKEN: ${{ secrets.LINKTREE_TOKEN }}
Store your authentication token as a secret. Never commit auth-token.json or tokens to version control.

​
Next steps

CLI Reference

See all deploy command options

Build

Learn about the build process