Geins Studio

Why use Geins Studio?

Comprehensive administrative interface

Geins Studio is a comprehensive administrative interface designed for e-commerce solutions that seamlessly integrates Geins PIM, CRM, WMS, CMS, and other essential tools into a unified, user-friendly platform.

Developer-friendly experience

Built with modern technologies and full TypeScript support, Geins Studio provides intelligent autocomplete, type safety, and excellent developer experience. The application uses a repository pattern to provide a consistent and type-safe interface for interacting with the Geins API.

Open source and customizable

Geins Studio is fully customizable and open source under the MIT License. Own your code and extend your Geins Studio to your specific business needs with the flexibility to modify and enhance any part of the application.

Production-ready

Built on Nuxt.js and compatible with modern deployment platforms, Geins Studio is production-ready and designed for real-world commerce operations. The application includes comprehensive authentication, state management, and responsive design for managing commerce operations at scale.

Getting started

Prerequisites

Before setting up Geins Studio, ensure you have:

• Node.js (v20.0.0 or higher)
• A Geins account

Installation

Clone the repository to create your own project.

Then install dependencies:

npm install

yarn install

pnpm install

Environment configuration

Create an .env file in the project root and configure the following variables:

• GEINS_API_URL - The URL to the Geins API (required)
• AUTH_SECRET - A secret key used to hash tokens, sign and encrypt cookies (required)
• BASE_URL - The URL to the application (required in production)
• GEINS_DEBUG - Debug flag (optional)

Start development

The application will be running at http://localhost:3000.

What can you build?

Geins Studio serves as a foundation for building:

• E-commerce admin interfaces - Manage products, categories, inventory, and pricing with a complete PIM system
• Customer management portals - Handle customer relationships, authentication, and user management through integrated CRM
• Wholesale management systems - Manage wholesale accounts, price lists, and B2B operations
• Order management dashboards - Track and manage orders with comprehensive order management features
• Multi-tenant platforms - Support multiple accounts and channels with built-in multi-account authentication

Core features

Authentication & User Management

Geins Studio uses a JWT-based authentication system built upon @sidebase/nuxt-auth. The authentication flow includes:

• Login with credentials and multi-factor authentication (MFA) support
• Multi-account selection for users with access to multiple accounts
• Automatic token refresh and session management
• Global authentication middleware protecting all routes

Repository Pattern API

The application uses a repository pattern providing consistent, type-safe interfaces for API interactions. Core repositories include:

• Global Repository - System-wide operations for accounts, channels, and currencies
• Product Repository - Specialized repository for product-related operations
• Wholesale Repository - Repository for wholesale operations
• Customer Repository - Repository for customer management
• Order Repository - Repository for order management
• User Repository - Repository for user operations

Access repositories easily through the useGeinsRepository composable.

Entity Management

The concept of entities is used throughout the application to dynamically handle various types of content data such as products, categories, users, and more. This provides a flexible and reusable approach to managing different data types.

Entity pages follow a consistent URL pattern: /{parent}/{entity}/{id} for individual items, /{parent}/{entity}/list for list views, and /{parent}/{entity}/new for creation.

Generic type definitions ensure type safety and consistency.

Wholesale Management

Recent enhancements include comprehensive wholesale capabilities:

• Wholesale accounts management
• Price lists with advanced product selection and quantity-based pricing
• Global price list rules
• Orders grid for wholesale accounts

State Management

The application uses Pinia for state management with dedicated stores for:

• Account management
• User data and authentication state
• Product data
• Breadcrumb navigation

Repository structure

Geins Studio follows a clean, organized structure for easy navigation and development.

The main directories include:

• app/ - Core application code including components, composables, layouts, pages, and stores
• server/ - Server-side API routes and utilities including authentication handlers
• shared/ - Shared types and utilities used across the application
• docs/ - VitePress documentation site
• i18n/ - Internationalization files
• test/ - Test suites and utilities

This structure promotes:

• Clear separation of concerns - Client-side, server-side, and shared code are clearly separated
• Type safety - Shared types ensure consistency across the application
• Documentation - Documentation lives alongside the code using VitePress
• Developer experience - Well-organized structure makes it easy to find and modify code

Technology stack

Geins Studio is built with modern, production-ready technologies:

Core technologies

• Nuxt.js - Vue.js framework for building performant web applications
• TypeScript - Full TypeScript implementation for type safety and excellent developer experience
• Vue 3 - Modern reactive JavaScript framework

UI & Styling

• shadcn-vue - Re-usable component library built on Radix Vue
• Tailwind CSS - Utility-first CSS framework for rapid UI development
• Lucide Icons - Beautiful, consistent icon set

State & Data Management

• Pinia - Official state management library for Vue
• VeeValidate + Zod - Form validation with schema-based validation
• TanStack Table - Headless table library for building data tables

Authentication & Security

• @sidebase/nuxt-auth - Authentication module for Nuxt
• NextAuth.js - Complete authentication solution
• JWT Decode - JWT token handling

Development tools

• ESLint - Code linting and formatting
• Prettier - Code formatting with Vue and Tailwind CSS plugins
• Vitest - Unit testing framework
• Changelogen - Automated changelog generation
• VitePress - Documentation site generator

Package management

The application uses Yarn as its package manager and requires Node.js version 20 or higher.

Theming and customization

Geins Studio is fully customizable with Tailwind CSS and shadcn-vue. The theme can be modified in the main CSS file, and the application includes built-in color mode support with light and dark themes.

For detailed theming instructions, explore:

• shadcn-vue Themes
• Tailwind CSS Documentation

The design system documentation can be found in the getting started guide.

Deployment

Geins Studio is designed for flexible deployment options. The application is configured as a Single Page Application (SPA) and can be deployed to various platforms.

A Dockerfile is included for containerized deployments. The Nuxt configuration supports custom Nitro presets for different deployment targets.

Repository resources

Official links

• GitHub Repository - github.com/geins-io/geins-studio - Source code, issues, and pull requests
• Documentation Site - Full documentation with VitePress (hosted in docs/ within the repository)
• Geins Platform - Get a free trial

Contributing

Geins Studio is open source, and contributions are welcome! Whether you're fixing bugs, adding features, improving documentation, or reporting issues, your contributions help make Geins Studio better for everyone.

To get started:

1. Report issues - Found a bug or have a feature request? Open an issue on GitHub
2. Submit pull requests - Contribute improvements and new features
3. Improve documentation - Help make the documentation clearer and more comprehensive
4. Share feedback - Let us know what features would improve your experience

Recent updates

The latest version (0.1.1) includes enhancements to wholesale functionality, comprehensive developer documentation updates, and improved code organization.

Version 0.1.0 introduced major features including wholesale accounts, price lists, responsive design, and Vercel analytics integration.

Notes

Geins Studio is currently in an early stage of development with features and integrations being continuously added. The application serves as a robust foundation and is built to be easily extendable as new features are developed.

The architecture emphasizes flexibility and type safety through the repository pattern, generic entity types, and comprehensive TypeScript support throughout the codebase. This makes it straightforward to extend the application with new entity types, API integrations, and custom business logic.