basicstack.org/README.md

BasicStack Frontend

Vue 3 / Nuxt 3 frontend for basicstack.org with Directus CMS integration.

Tech Stack

• Vue 3 with Composition API
• Nuxt 3 (SSR/SSG, file-based routing)
• TypeScript for type safety
• Directus SDK for headless CMS integration
• @nuxt/image for optimized image handling
• @nuxtjs/sitemap for SEO

Features

• Responsive mobile-first design
• SEO-optimized with meta tags and sitemap
• Directus API integration for dynamic content
• Static site generation (SSG) ready
• TypeScript types for Directus schema

Project Structure

basicstack-frontend/
├── assets/          # CSS and static assets
├── components/      # Vue components
│   └── Navigation.vue
├── composables/     # Composables
│   └── useDirectus.ts  # Directus client & API functions
├── layouts/         # Nuxt layouts
│   └── default.vue
├── pages/           # File-based routing
│   ├── index.vue
│   ├── [slug].vue   # Generic content pages
│   ├── packages/
│   │   ├── index.vue
│   │   └── [slug].vue
│   └── infrastructure/
│       ├── index.vue
│       └── [slug].vue
├── public/          # Public static files
├── .env             # Environment variables
├── nuxt.config.ts   # Nuxt configuration
└── package.json

Routes

• / - Home page
• /packages - Software packages listing
• /packages/:slug - Package detail page
• /infrastructure - Infrastructure overview
• /infrastructure/:slug - Infrastructure topic detail
• /:slug - Generic content pages (About, Contact, etc.)

Setup

Prerequisites

• Node.js 18+ and npm
• Access to Directus instance at https://directus.basicstack.de

Installation

# Install dependencies
npm install

# Create .env file (already created)
cp .env.example .env

# Edit .env if needed
nano .env

Environment Variables

DIRECTUS_URL=https://directus.basicstack.de
SITE_URL=https://basicstack.org

Development

# Start dev server (http://localhost:3000)
npm run dev

Production

# Build for production (SSR)
npm run build

# Preview production build
npm run preview

# Generate static site (SSG)
npm run generate

Directus Integration

The application connects to Directus using the @directus/sdk package. All API calls are made through the useDirectus() composable.

Collections

• software_packages - Software package listings
• package_screenshots - Package screenshots
• package_deployment_details - Deployment information
• package_troubleshooting - Troubleshooting guides
• infrastructure_content - Infrastructure documentation
• pages - Generic content pages
• navigation - Site navigation menu

Example Usage

const { getPackages, getPackage, getAssetUrl } = useDirectus()

// Get all published packages
const packages = await getPackages()

// Get a specific package by slug
const pkg = await getPackage('directus')

// Get asset URL for a Directus file
const logoUrl = getAssetUrl(pkg.logo)

Design Integration

The frontend is scaffolded with basic responsive styling. Corporate design tokens and components from DEV-171 can be integrated as they become available without requiring architectural changes.

Deployment

The application can be deployed as:

1. SSR (Node.js server) - Default mode, best for dynamic content
2. SSG (Static site) - Pre-rendered pages, best for CDN hosting
3. Hybrid - Mix of SSR and SSG based on routes

Recommended deployment targets:

• Kubernetes (with Node.js container)
• Vercel / Netlify (for SSG)
• Any Node.js hosting platform

SEO

• Meta tags configured per page
• Sitemap.xml automatically generated
• Semantic HTML structure
• Open Graph tags ready for social sharing

Next Steps

1. ✅ Nuxt 3 application scaffolded
2. ✅ Directus SDK integrated
3. ✅ All required pages/routes created
4. ✅ Responsive layout implemented
5. ✅ SEO basics in place
6. ⏳ Apply corporate design tokens from DEV-171
7. ⏳ Deploy to Kubernetes with TLS
8. ⏳ Content population via Directus

Related Issues

• DEV-172 - Directus schema (dependency)
• DEV-171 - Corporate design (soft dependency)
• DEV-169 - Parent issue

License

See LICENSE file in repository root.