Deployment

Deploy your LinkApp to Linktree

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:

Production

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

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

Flag	Description
--qa	Deploy to QA environment instead of production
--skip-build	Skip building (use existing dist/)
--skip-checks	Skip pre-deployment validation
--force	Force 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