First Steps Tutorial

Overview

Learn the fundamentals by exploring the codebase and making your first changes

Now that you have Portfolio OS running, let's take a tour and make some changes to get comfortable with the codebase.

Understanding the Monorepo Structure

Portfolio OS uses a monorepo architecture with Turborepo and PNPM workspaces:

Tutorial 1: Explore the Site App

Let's start by understanding the main portfolio site.

export default async function HomePage() {
  return (
    <div className="flex flex-col gap-8">
      <h1 className="text-4xl font-bold">
        Welcome to My Portfolio // [!code --]
        Hello! I'm Building Something Awesome // [!code ++]
      </h1>
      {/* Rest of the component */}
    </div>
  )
}

Tutorial 2: Working with Shared Packages

One of the key benefits of the monorepo is code sharing. Let's see how packages work.

import { Button } from "@mindware-blog/ui"

export default function HomePage() {
  return (
    <div>
      <Button>Click Me</Button>
    </div>
  )
}

const buttonVariants = cva(
  "inline-flex items-center justify-center...",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        destructive: "bg-destructive text-destructive-foreground",
        outline: "border border-input bg-background",
        // Add your custom variant // [!code ++]
        custom: "bg-purple-600 text-white hover:bg-purple-700", // [!code ++]
      },
    },
  }
)

<Button variant="custom">Custom Style</Button>

Tutorial 3: Understanding Data Flow

Let's explore how Portfolio OS fetches and displays blog posts from Hashnode.

export async function getAllPosts() {
  const response = await fetch(HASHNODE_API_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: GET_ALL_POSTS_QUERY }),
  })
  return response.json()
}

Tutorial 4: Working with the Dashboard

The dashboard app provides admin functionality for content management.

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String
  published Boolean  @default(false)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

import { prisma } from "@mindware-blog/db"

export async function getPosts() {
  return await prisma.post.findMany({
    where: { published: true },
    orderBy: { createdAt: "desc" },
  })
}

Common Development Tasks

Now that you understand the basics, here are common tasks you'll perform:

Running Commands

# Run all apps
pnpm dev

# Run specific app
pnpm dev --filter=@mindware-blog/site
pnpm dev --filter=@mindware-blog/dashboard

# Run multiple specific apps
pnpm dev --filter=@mindware-blog/site --filter=@mindware-blog/dashboard

Adding a New Package

# Create new package directory
mkdir packages/my-new-package
cd packages/my-new-package

# Initialize package
pnpm init

# Add to workspace (automatically detected)
# Add dependencies
pnpm add some-dependency

# Use in app
# In apps/site/package.json, add:
# "@mindware-blog/my-new-package": "workspace:*"

Database Migrations

# Create a migration
cd apps/dashboard
pnpm prisma migrate dev --name add_new_field

# Apply migrations
pnpm prisma migrate deploy

# Open Prisma Studio to browse data
pnpm prisma studio

Understanding Turborepo

Portfolio OS uses Turborepo for build orchestration:

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Key Concepts:

• ^build: Build dependencies first
• outputs: Cache these directories
• persistent: Keep dev servers running

Next Steps

You're now familiar with the basics! Here's what to explore next:

Tips for Success

Getting Help

Need assistance?

• Documentation: You're in the right place! Explore the sidebar.
• Troubleshooting: Check Common Issues
• GitHub Issues: Open an issue for bugs or feature requests
• Developer Guide: See Architecture for deeper concepts