177 lines
4.4 KiB
Markdown
177 lines
4.4 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Install dependencies
|
||
|
|
npm install
|
||
|
|
|
||
|
|
# Create .env file (already created)
|
||
|
|
cp .env.example .env
|
||
|
|
|
||
|
|
# Edit .env if needed
|
||
|
|
nano .env
|
||
|
|
```
|
||
|
|
|
||
|
|
### Environment Variables
|
||
|
|
|
||
|
|
```bash
|
||
|
|
DIRECTUS_URL=https://directus.basicstack.de
|
||
|
|
SITE_URL=https://basicstack.org
|
||
|
|
```
|
||
|
|
|
||
|
|
## Development
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Start dev server (http://localhost:3000)
|
||
|
|
npm run dev
|
||
|
|
```
|
||
|
|
|
||
|
|
## Production
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
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](/DEV/issues/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](/DEV/issues/DEV-172) - Directus schema (dependency)
|
||
|
|
- [DEV-171](/DEV/issues/DEV-171) - Corporate design (soft dependency)
|
||
|
|
- [DEV-169](/DEV/issues/DEV-169) - Parent issue
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
See LICENSE file in repository root.
|