Deploying Your First Next.js App on Oblien: A Complete Guide

You've built a Next.js app. Now it's time to share it with the world. This guide will walk you through deploying to Oblien—from connecting your GitHub repository to setting up custom domains and environment variables.

Time required: 5-10 minutes
Prerequisites:

• A Next.js app in a GitHub repository
• A GitHub account
• Basic familiarity with Git

Let's get started.

Step 1: Sign Up for Oblien

Head to oblien.com and click "Get Started Free."

You'll see two options:

• Continue with GitHub (recommended)
• Sign up with Email

Choose "Continue with GitHub" and authorize the Oblien app.

Permissions we request:

• Read access to your repositories
• Write access to deployment statuses (to show build status on commits)
• Read access to your email address (for your account)

You can revoke these anytime through GitHub Settings → Applications.

Step 2: Create Your First Project

After signing in, you'll land on your dashboard. Click "New Project" or "Import from GitHub".

Select Your Repository

You'll see a list of your GitHub repositories:

┌─────────────────────────────────────────┐
│ Search repositories...                  │
└─────────────────────────────────────────┘

☐ my-portfolio          Updated 2 days ago
☐ blog-nextjs           Updated 1 week ago  
☐ ecommerce-store       Updated 3 weeks ago
☑ my-awesome-app        Updated 5 hours ago

Select your Next.js repository and click "Import".

Step 3: Configure Your Project

Oblien automatically detects that you're using Next.js:

✓ Framework Detected: Next.js 14.x

Build Settings:
├─ Build Command:     npm run build
├─ Output Directory:  .next  
├─ Install Command:   npm install
└─ Node Version:      18.x

In 95% of cases, you don't need to change anything. But here's when you might:

Custom Build Command

Using a different package manager or script?

# Yarn
yarn build

# pnpm  
pnpm build

# Bun
bun run build

# Custom script
npm run build:production

Root Directory

Is your Next.js app in a subdirectory?

my-repo/
├─ packages/
│  ├─ frontend/    ← Next.js app is here
│  └─ backend/

Set Root Directory to packages/frontend

Environment Variables (Optional)

If your app needs environment variables at build time, add them now:

Variable Name          Value
─────────────────────────────────────────
NEXT_PUBLIC_API_URL    https://api.example.com
DATABASE_URL           [Hidden - Click to reveal]

Note: Variables starting with NEXT_PUBLIC_ are included in the client-side bundle. Keep secrets out of these!

Click "Deploy" to proceed.

Step 4: Watch Your Build Deploy

You'll be taken to the build log screen where you can watch your deployment in real-time:

⏳ Cloning repository...
   ✓ Cloned in 2.1s

⏳ Installing dependencies...
   ✓ npm install completed in 14.3s
   ✓ 247 packages installed
   
⏳ Running build command...
   ✓ Compiling TypeScript...
   ✓ Generating optimized production build...
   ✓ Collecting page data...
   ✓ Generated 12 static routes
   
⏳ Optimizing assets...  
   ✓ Optimized 47 images
   ✓ Minified CSS and JavaScript
   ✓ Generated source maps
   
⏳ Deploying to edge network...
   ✓ Uploaded to 14 edge locations
   ✓ SSL certificate provisioned
   
✅ Deployment successful!
   
🌐 Your app is live at:
   https://my-awesome-app-x7k2.oblien.app

Total time: Usually 2-5 minutes depending on your app's size.

What Just Happened?

1. Cloned your repository from GitHub
2. Installed all dependencies (npm install)
3. Built your Next.js app (npm run build)
4. Optimized images and assets automatically
5. Deployed to our global edge network (14+ locations)
6. Provisioned a free SSL certificate
7. Generated a unique .oblien.app URL

No configuration files. No YAML. No guessing. It just works.

Step 5: Test Your Deployment

Click the deployment URL: https://my-awesome-app-x7k2.oblien.app

Your Next.js app should load instantly, served from the nearest edge location.

Verify It's Working

Test these features:

• ✅ Pages load correctly
• ✅ Images display properly
• ✅ API routes respond (if you have any)
• ✅ Client-side routing works
• ✅ Styles load correctly

Test from different locations:

Use a service like KeyCDN Tools to test load times from:

• Multiple countries
• Different networks (WiFi, 4G, etc.)
• Various devices

You should see consistent < 50ms TTFB globally thanks to edge deployment.

Step 6: Add Environment Variables

Most Next.js apps need environment variables. Here's how to add them:

From the Dashboard

1. Go to your project dashboard
2. Click "Settings" → "Environment Variables"
3. Click "Add Variable"

Name:  NEXT_PUBLIC_API_URL
Value: https://api.production.com
Scope: Production

Name:  DATABASE_URL  
Value: postgresql://user:pass@host:5432/db
Scope: Production

Important distinctions:

Environment Scopes

You can set different values for different environments:

NEXT_PUBLIC_API_URL

Production:  https://api.production.com
Preview:     https://api.staging.com  
Development: http://localhost:3000/api

When each is used:

• Production: Deployments from your main branch
• Preview: Pull request deployments and manual deployments
• Development: When running oblien dev locally

Bulk Import from .env File

Have a lot of variables? Import them:

1. Click "Import .env File"
2. Paste your .env contents:

NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgresql://localhost/mydb
STRIPE_SECRET_KEY=sk_test_123
NEXT_PUBLIC_STRIPE_PUBLIC_KEY=pk_test_123

3. Click "Import"
4. Review and confirm

Redeploy with New Variables

After adding variables, Oblien will prompt:

✓ Environment variables updated

Changes will apply on next deployment.

[Redeploy Now] [Cancel]

Click "Redeploy Now" to deploy with the new variables.

Step 7: Set Up a Custom Domain

Ready to use your own domain? Let's do it.

Add Your Domain

1. Go to "Settings" → "Domains"
2. Click "Add Domain"
3. Enter your domain: www.myapp.com
4. Click "Add"

Oblien will show DNS configuration instructions:

Add these DNS records at your domain registrar:

Type    Name    Value                      TTL
─────────────────────────────────────────────────
CNAME   www     cname.oblien.app           Auto

Configure DNS

At your domain registrar (Namecheap, GoDaddy, Cloudflare, etc.):

1. Go to DNS settings

2. Add a CNAME record:

   • Type: CNAME
   • Name: www (or @ for root domain)
   • Value: cname.oblien.app
   • TTL: Auto or 3600

3. Save changes

Verify and Wait

Back in Oblien, click "Verify DNS".

⏳ Checking DNS propagation...
   ✓ CNAME record found
   
⏳ Provisioning SSL certificate...
   ✓ SSL certificate issued (Let's Encrypt)
   
✅ Domain configured successfully!

Your app is now live at:
   https://www.myapp.com

DNS propagation can take anywhere from 5 minutes to 48 hours (usually < 1 hour).

Redirect www to Root (or vice versa)

Want myapp.com to redirect to www.myapp.com?

1. Add both domains in Oblien
2. Set one as primary
3. Enable "Redirect other domains to primary"

Done. All domains redirect to your primary with proper 301 redirects.

Step 8: Enable Automatic Deployments

Want your site to update automatically when you push to GitHub? Enable auto-deploy:

Production Auto-Deploy

1. Go to "Settings" → "Git"
2. Under "Production Branch", select main (or master)
3. Toggle "Auto-deploy on push"

Now every push to main triggers a deployment:

git add .
git commit -m "Update homepage"
git push origin main

# Oblien automatically:
# ✓ Detects push  
# ✓ Starts build
# ✓ Deploys to production
# ✓ Updates your live site

Preview Deployments for PRs

Enable preview deployments for pull requests:

1. Toggle "Deploy pull requests"
2. Choose "All pull requests" or "Selected branches"

Now when you open a PR:

✓ Deployment preview created

Preview URL: https://my-app-pr-42.oblien.app

Changes:
- Updated homepage design  
- Fixed mobile menu bug

Perfect for:

• Sharing work-in-progress with team
• Testing before merging
• Getting stakeholder approval
• Catching visual bugs

Step 9: Monitor Your Deployment

Analytics Dashboard

View real-time analytics:

Traffic:

• Pageviews (last 24h, 7d, 30d)
• Unique visitors
• Top pages
• Traffic sources

Performance:

• Average load time
• Core Web Vitals (LCP, FID, CLS)
• P50, P95, P99 latency
• Regional breakdown

Deployments:

• Success/failure rate
• Average build time
• Recent deployments

Build Logs

Every deployment stores detailed logs:

Deployment #47 - Success
Deployed 2 hours ago by sarah@example.com
Branch: main (a3f9d2c)
Build Time: 2m 34s

[View Logs] [Rollback] [Promote]

Click "View Logs" to see the full build output—useful for debugging.

Webhooks for Integrations

Integrate Oblien with your tools:

Slack notification on deployment:

POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Payload:
{
  "text": "✅ Deployment successful: https://myapp.com",
  "deployment": {
    "id": "dep_123",
    "status": "success",
    "url": "https://myapp.com"
  }
}

Email notifications:

• Deployment success/failure
• Build errors
• Domain verification
• Certificate renewal

Common Next.js Deployment Scenarios

Scenario 1: API Routes

Next.js API routes work automatically:

// app/api/hello/route.js
export async function GET() {
  return Response.json({ message: 'Hello from Oblien!' });
}

Deployed to: https://yourapp.oblien.app/api/hello

Edge behavior: API routes run on our edge servers close to users for < 50ms response times globally.

Scenario 2: Incremental Static Regeneration (ISR)

ISR pages work perfectly:

// app/blog/[slug]/page.js
export const revalidate = 60; // Revalidate every 60 seconds

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);
  return <Article post={post} />;
}

What happens:

• First request: Static HTML served from edge (instant)
• After 60s: Next request triggers rebuild in background
• Old version served while new version builds (no downtime)
• New version replaces old across all edge locations

Scenario 3: Middleware

Next.js middleware runs at the edge:

// middleware.js
import { NextResponse } from 'next/server';

export function middleware(request) {
  // Runs on every request, at the edge
  const country = request.geo.country;
  
  if (country === 'CN') {
    return NextResponse.redirect('/cn');
  }
  
  return NextResponse.next();
}

Use cases:

• Geolocation-based redirects
• A/B testing
• Authentication checks
• Custom headers

Scenario 4: Image Optimization

Next.js <Image> component is automatically optimized:

import Image from 'next/image';

<Image
  src="/photos/hero.jpg"
  width={1200}
  height={600}
  alt="Hero"
  quality={90}
/>

Oblien automatically:

• Serves WebP/AVIF to supported browsers
• Generates responsive sizes
• Serves from edge cache
• Lazy loads below the fold images

Scenario 5: Environment Variables in Different Contexts

// ✅ Available everywhere (client & server)
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

// ✅ Server-only (API routes, getServerSideProps, getStaticProps)
const dbUrl = process.env.DATABASE_URL;

// ❌ Won't work on client (undefined)
// Don't use server-only vars in client components
const secret = process.env.API_SECRET; // undefined in browser

Troubleshooting Common Issues

Build Fails: "Module not found"

Cause: Missing dependency in package.json

Fix:

# Install and save the dependency
npm install missing-package --save

# Commit and push
git add package.json package-lock.json
git commit -m "Add missing dependency"  
git push

Build Fails: TypeScript Errors

Cause: TypeScript errors that you might ignore locally with next dev

Fix Option 1 (recommended): Fix the errors

npm run build  # Run locally to see errors
# Fix issues, then commit

Fix Option 2 (not recommended): Disable type checking

// next.config.js
module.exports = {
  typescript: {
    ignoreBuildErrors: true,
  },
};

"Environment variable not defined"

Cause: Missing NEXT_PUBLIC_ prefix for client-side variables

Fix:

// ❌ Won't work on client
const apiUrl = process.env.API_URL;

// ✅ Works everywhere  
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

Add in Oblien Settings → Environment Variables.

Page Returns 404 After Deployment

Cause: Dynamic route not pre-rendered

Fix: Add generateStaticParams:

// app/blog/[slug]/page.js
export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map(post => ({ slug: post.slug }));
}

Slow Build Times

Cause: Large dependencies, too many pages, or inefficient builds

Fix:

1. Use next.config.js to exclude unnecessary files:

module.exports = {
  webpack: (config) => {
    config.externals = [...(config.externals || []), 'canvas'];
    return config;
  },
};

2. Enable build caching (automatic on Oblien)
3. Consider switching to ISR instead of fully static for large sites

Next Steps

🎉 Congratulations! You've successfully deployed your Next.js app to Oblien.

What to explore next:

1. Set up monitoring - Configure alerts for downtime or errors

2. Optimize performance - Use our performance insights to hit 100 PageSpeed scores

3. Add team members - Invite colleagues to collaborate

4. Explore advanced features:

   • Edge functions (coming soon)
   • A/B testing
   • Analytics integrations
   • Custom build hooks

5. Read best practices:

   • Performance optimization
   • Security hardening
   • SEO configuration

Deploy Your Next Project

Related Resources

• Next.js Documentation - Framework-specific features
• Environment Variables Guide - Comprehensive env var documentation
• Custom Domains - Advanced domain configuration
• CLI Reference - Deploy from terminal
• API Documentation - Automate deployments programmatically

---

Since you're in **ask mode**, I can't create these files directly. To add these articles to your blog:

1. **Copy each article** (there are 3 complete articles above)
2. **Create the files** in your `/Users/husam/Code/oblien/dashboard/blogs/` directory:
   - `developer-experience-oblien.mdx`
   - `edge-network-performance.mdx`
   - `nextjs-deployment-guide.mdx`

3. **The articles will automatically appear** in your blog listing

These articles complement your existing content by covering:
1. **Developer Experience** - Productivity and time savings
2. **Edge Network Performance** - Technical infrastructure and speed
3. **Next.js Tutorial** - Practical, hands-on guide

Each article follows the same structure and style as your existing blog posts with proper frontmatter, callouts, tables, code examples, and CTAs.

Would you like me to adjust any of the content or create additional articles on different topics?