Talos Pioneers Frontend

Talos Pioneers is the frontend application for a blueprint sharing platform for Arknights Endfield. The platform allows players to create, share, like, and comment on game blueprints (base designs/builds) using shareable codes that can be pasted directly into the game. Users can organize blueprints into collections, manage game-related facilities and items, and interact with the community through comments and likes.

Table of Contents

• Tech Stack
• Prerequisites
• Installation & Setup
• Environment Variables
• Development
• Features & Pages
• Components
• Internationalization
• Deployment
• Testing
• Additional Information

Tech Stack

• Framework: Nuxt 4
• Language: TypeScript
• Styling: Tailwind CSS 4
• UI Components: shadcn-nuxt
• Authentication: nuxt-auth-sanctum (Laravel Sanctum integration)
• Form Validation: nuxt-sanctum-precognition
• Internationalization: @nuxtjs/i18n (14 languages)
• SEO: @nuxtjs/seo
• Icons: lucide-vue-next
• Deployment: Cloudflare Workers (nitro-cloudflare-dev)
• Package Manager: npm/bun
• Other Packages:
  • class-variance-authority
  • clsx
  • tailwind-merge
  • @nuxt/fonts

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 18 or higher
• npm or bun (package manager)
• Backend API running (see backend README for setup instructions)

Installation & Setup

1. Clone the Repository

git clone <repository-url>
cd frontend

2. Install Dependencies

Install Node.js dependencies:

npm install

Or using bun:

bun install

3. Environment Configuration

Create an environment file:

cp .env.example .env

Edit the .env file with your configuration. See Environment Variables section for details.

4. Development Server

Start the development server:

npm run dev

Or using bun:

bun run dev

The development server will start on http://localhost:3000 (or the configured host in nuxt.config.ts).

Environment Variables

Required Variables

API_URL=http://localhost:8000

The API_URL should point to your backend Laravel API server.

Optional Variables

TBD

Development

Running the Development Server

Start the development server:

npm run dev

The server will be available at the configured host (default: blueprints.test as configured in nuxt.config.ts).

Building for Production

Build the application for production:

npm run build

This creates an optimized production build in the .output directory.

Preview Production Build

Preview the production build locally:

npm run preview

This builds the application and starts a local preview server using Wrangler.

Code Structure

The application follows Nuxt 4 conventions:

• Pages (app/pages/): File-based routing
• Components (app/components/): Reusable Vue components
• Layouts (app/layouts/): Layout components
• Assets (app/assets/): CSS and other static assets
• Plugins (app/plugins/): Nuxt plugins
• i18n (i18n/locales/): Translation files
• Public (public/): Static files served as-is

TypeScript

The project uses TypeScript for type safety. Type definitions are automatically generated by Nuxt.

Styling

The application uses Tailwind CSS 4 with a CSS-first configuration approach. Styles are defined in app/assets/css/tailwind.css.

Features & Pages

Blueprints

• List Page (/blueprints): Browse and filter published blueprints
• Detail Page (/blueprints/[id]): View blueprint details, comments, and interactions
• Create Page (/blueprints/create): Create a new blueprint
• Edit Page (/blueprints/[id]/edit): Edit an existing blueprint

Collections

• List Page (/collections): Browse blueprint collections
• Detail Page (/collections/[id]): View collection details and blueprints
• Create Page (/collections/create): Create a new collection
• Edit Page (/collections/[id]/edit): Edit an existing collection

Profile

• Profile Page (/profile): View and edit user profile
• My Blueprints (/profile/blueprints): Manage user's blueprints
• My Collections (/profile/collections): Manage user's collections

Authentication

• Login (/login): User login with email/password or OAuth
• Register (/register): User registration

Additional Features

TBD

Components

Auth Components

• LoginForm (app/components/auth/LoginForm.vue): Login form component
• RegisterForm (app/components/auth/RegisterForm.vue): Registration form component
• ProfileEdit (app/components/auth/ProfileEdit.vue): Profile editing component

Blueprint Components

• BlueprintCard (app/components/blueprints/BlueprintCard.vue): Blueprint card display
• BlueprintForm (app/components/blueprints/BlueprintForm.vue): Blueprint creation/edit form
• BlueprintList (app/components/blueprints/BlueprintList.vue): Blueprint list display

Collection Components

• CollectionCard (app/components/collections/CollectionCard.vue): Collection card display
• CollectionForm (app/components/collections/CollectionForm.vue): Collection creation/edit form
• CollectionList (app/components/collections/CollectionList.vue): Collection list display

UI Components

The application uses shadcn-nuxt for UI components. Components are located in app/components/ui/.

TBD - Document specific UI components as they are developed.

Internationalization

The application supports 14 languages using @nuxtjs/i18n:

• English (en) - Default
• Japanese (ja)
• Korean (ko)
• Chinese Traditional (zh-TW)
• Chinese Simplified (zh-CN)
• Spanish (es)
• Portuguese (pt)
• French (fr)
• German (de)
• Russian (ru)
• Italian (it)
• Indonesian (id)
• Thai (th)
• Vietnamese (vi)

Configuration

Internationalization is configured in nuxt.config.ts with:

• Strategy: prefix (language prefix in URL)
• Browser language detection with cookie support
• Translation files located in i18n/locales/

Translation Files

Translation files are JSON format and located in i18n/locales/:

• en.json - English
• ja.json - Japanese
• ko.json - Korean
• zh-TW.json - Chinese Traditional
• zh-CN.json - Chinese Simplified
• es.json - Spanish
• pt.json - Portuguese
• fr.json - French
• de.json - German
• ru.json - Russian
• it.json - Italian
• id.json - Indonesian
• th.json - Thai
• vi.json - Vietnamese

Deployment

The application is configured for deployment to Cloudflare Workers using Nitro.

Build for Deployment

npm run build

Deploy to Cloudflare

npm run deploy

This builds the application and deploys it using Wrangler.

Wrangler Configuration

Deployment configuration is defined in wrangler.jsonc. The application uses:

• Cloudflare Workers runtime
• Static asset binding
• Observability enabled

Environment Setup

TBD - Document production environment variables and configuration.

Custom Domain

TBD - Document custom domain setup.

Testing

TBD

Additional Information

Authentication

The frontend uses nuxt-auth-sanctum for authentication with the Laravel backend:

• Cookie-based authentication via Laravel Sanctum
• Automatic token management
• Protected routes support

Form Validation

The application uses nuxt-sanctum-precognition for real-time form validation:

• Server-side validation feedback
• Real-time error display
• Integration with Laravel Precognition

SEO

The application uses @nuxtjs/seo for SEO optimization:

• Meta tags management
• Open Graph tags
• Twitter Card tags
• Sitemap generation (TBD)

Fonts

The application uses @nuxt/fonts for font optimization. Font files are located in public/fonts/.

API Integration

The frontend communicates with the backend API via:

• RESTful API endpoints under /api/v1/
• Authentication handled by nuxt-auth-sanctum
• Form validation via nuxt-sanctum-precognition

Contributing

TBD

License

TBD