Skip to main content
This guide walks you through deploying your React + TypeScript portfolio to Netlify, including serverless functions and environment configuration.

​
Prerequisites

Before you begin, ensure you have:
  • A GitHub account with your repository
  • A Netlify account (sign up at netlify.com)
  • Azure AI API token
  • GitHub API token (optional, for repository data)

​
Initial Setup

1

Create Netlify Account

  1. Go to netlify.com
  2. Click “Sign up” and choose “Sign up with GitHub”
  3. Authorize Netlify to access your GitHub account
2

Import Your Repository

  1. From your Netlify dashboard, click “Add new site”
  2. Select “Import an existing project”
  3. Choose “Deploy with GitHub”
  4. Select your portfolio repository from the list
3

Configure Build Settings

Netlify should auto-detect your settings from netlify.toml, but verify:
  • Build command: npx convex deploy --cmd "npm run build"
  • Publish directory: dist
  • Functions directory: netlify/functions
  • Node version: 20
4

Set Environment Variables

Before deploying, configure your environment variables (see below)
5

Deploy

Click “Deploy site” to trigger your first deployment

​
Environment Variables Configuration

1

Navigate to Environment Settings

In your Netlify site dashboard:
  1. Click on “Site settings”
  2. Navigate to “Environment variables” in the left sidebar
2

Add Required Variables

Add the following environment variables:
API_TOKEN=your_azure_ai_api_token_here
3

Choose Deployment Contexts

For each variable, select which contexts should have access:
  • Production: Required
  • Deploy Previews: Recommended
  • Branch deploys: Optional
Never commit API tokens to your repository. Always configure them as environment variables in Netlify.

​
Netlify Configuration File

Your netlify.toml file should be in the root of your repository:
netlify.toml
[build]
  command = "npx convex deploy --cmd \"npm run build\""
  publish = "dist"
  functions = "netlify/functions"

[build.environment]
  NODE_VERSION = "20"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[[headers]]
  for = "/*"
    [headers.values]
    Access-Control-Allow-Origin = "*"
    Access-Control-Allow-Methods = "GET, POST, OPTIONS"
    Access-Control-Allow-Headers = "Content-Type, Authorization"

​
Configuration Breakdown

  • build.command: Runs Convex deployment and Vite build
  • build.publish: Output directory for built assets
  • build.functions: Location of serverless functions
  • redirects: SPA routing support - redirects all routes to index.html
  • headers: CORS configuration for API requests

​
Local Testing

Test your site locally before deploying:
1

Install Netlify CLI

pnpm add -g netlify-cli
2

Login to Netlify

netlify login
This opens a browser window to authenticate
3

Link Your Site

netlify link
Select your site from the list or enter the site ID
4

Test Locally

netlify dev
This runs your site with Netlify Functions locally at http://localhost:8888
The netlify dev command automatically injects environment variables from your Netlify site, so you don’t need a .env file locally.

​
Manual Deployment

You can also deploy manually using the Netlify CLI: 
# Build your project
pnpm run build

# Deploy to a draft URL
netlify deploy

​
Automatic Deployments

By default, Netlify automatically deploys when you push to your repository:
  • Production deploys: Triggered on push to main branch
  • Deploy previews: Triggered on pull requests
  • Branch deploys: Optional, can be configured for specific branches

​
Configure Deploy Contexts

  1. Go to Site settings > Build & deploy > Continuous deployment
  2. Under “Deploy contexts”, configure:
    • Production branch: main
    • Branch deploys: All branches or specific branches
    • Deploy previews: Automatically build deploy previews for all pull requests

​
Monitoring and Debugging

​
View Build Logs

  1. Go to Deploys in your site dashboard
  2. Click on any deployment to view detailed logs
  3. Look for errors in the build output

​
Function Logs

  1. Go to Functions in your site dashboard
  2. Click on a function (e.g., chat)
  3. View real-time logs and invocation history

​
Common Build Issues

  • Verify netlify.toml is in the root directory
  • Check that all dependencies are listed in package.json
  • Ensure the build command works locally: pnpm run build
  • Check environment variables are configured correctly
  • View function logs in Netlify dashboard
  • Test functions locally using netlify dev
  • Verify the function path: netlify/functions/chat.ts
  • Ensure the redirect rule is in netlify.toml:
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
  • Verify CORS headers in netlify.toml
  • Check function CORS configuration in netlify/functions/chat.ts
  • Test API endpoints using browser DevTools or Postman

​
Performance Optimization

​
Build Plugin Recommendations

  1. netlify-plugin-cache: Cache dependencies between builds
  2. @netlify/plugin-lighthouse: Run Lighthouse checks on every deploy
Install via Netlify UI: Integrations > Build plugins

​
Asset Optimization

Vite automatically optimizes your assets during build:
  • JavaScript minification
  • CSS minification
  • Image optimization (for imported images)
  • Code splitting
  • Tree shaking
Your site is automatically deployed to Netlify’s global CDN for fast access worldwide.

​
Custom Domain

To add a custom domain:
1

Add Domain

  1. Go to Domain settings
  2. Click “Add custom domain”
  3. Enter your domain name
2

Configure DNS

Follow Netlify’s instructions to:
  • Add DNS records at your domain registrar, OR
  • Use Netlify DNS for easier management
3

Enable HTTPS

Netlify automatically provisions an SSL certificate via Let’s Encrypt

​
Next Steps

Environment Variables

Detailed guide to all environment variables

Serverless Functions

Configure Netlify Functions

Build docs developers (and LLMs) love

Get started for freeTalk to us