Nuxt starter

Why use Ralph Storefront?

Rapid time to market

Ralph Storefront eliminates weeks of initial setup and boilerplate code. By leveraging MACH technologies, this PWA launchpad provides a scalable and maintainable foundation that's ideal for optimizing your time to market and delivering a seamless user experience.

Production-ready out of the box

Everything is set up for you — start building your store right away. The launchpad comes with a test drive payment gateway and freight checkout, meaning you can test your store immediately without setting up a payment gateway or freight provider.

Component-rich architecture

Built tightly coupled with Ralph UI, a comprehensive component and core functionality library, Ralph Storefront provides dozens of reusable, production-tested components organized according to the Atomic Design methodology. Override any component or create new ones with simple CLI commands.

Developer-friendly experience

Hot reload development server and helpful CLI tools make development fast and enjoyable. Create components, override defaults, and generate image configurations with simple npm commands.

Open source and community-driven

Ralph Storefront is open source under the MIT License, meaning you can contribute improvements, customize for your needs, and benefit from community-driven enhancements. Full transparency and no lock-in.

Getting started

Prerequisites

• Node.js (v16.x.x or higher)
• A Geins account - Get started for free

Installation

Create a new project using the Geins CLI:

npx create-geins-app

Or clone the repository to create your own project.

Environment variables

In the root of the project, you will find an .env.example file. This file contains all the environment variables that are needed for the project to run.

If you only have one market, your DOMAINS variable should look like this: DOMAINS=sv|www.site.se. For your local dev environment the equivalent would be DOMAINS=sv|localhost:3000.

Start development

Install dependencies and start the development server with hot reload:

npm install
npm run dev

yarn install
yarn dev

pnpm install
pnpm dev

Your storefront will be available at http://localhost:3000.

What can you build?

Ralph Storefront empowers you to build:

• Progressive web applications - Full PWA support for app-like experiences on mobile and desktop
• Multi-market storefronts - Support multiple channels, markets, and languages with built-in internationalization
• Headless commerce solutions - Complete freedom over frontend design while leveraging Geins backend
• B2C and B2B stores - Customer type management for retail, wholesale, and hybrid commerce models
• Content-rich experiences - Integrated CMS with widgets, banners, and dynamic content areas

Core features

Full Geins integration

Ralph Storefront integrates with all major Geins systems:

• Product Information Management (PIM) - Complete product catalogs, variants, search, and filtering
• Content Management System (CMS) - Pages, menus, widgets, and content areas
• Order Management System (OMS) - Cart, checkout, and order processing
• Customer Relationship Management (CRM) - Authentication, profiles, and customer management
• Payment Gateway - Integrated payment processing with multiple providers
• Shipping Gateway - Freight calculation and shipping methods
• Transactional emails - Automated email notifications

Internationalization & Multi-market

Comprehensive i18n support includes:

• Multiple languages (English, Swedish, Norwegian, Danish, Finnish by default)
• Translated routes and content
• Multi-market support with separate domains or URL-based routing
• Market and language switching
• Localized currencies and formatting

Atomic Design architecture

Components are organized according to the Atomic Design methodology:

• Atoms - Basic building blocks like buttons, inputs, and icons
• Molecules - Combinations of atoms creating complex elements like forms and menus
• Organisms - Larger groups forming distinct sections like headers and product cards
• Templates - Page-level layouts combining organisms
• Pages - Final rendered pages users interact with

This structure promotes reusability, consistency, and maintainability.

Ralph UI component library

Ralph Storefront is built on Ralph UI, a comprehensive component and core functionality library. All functionality in this library can be easily overridden to meet your unique business requirements.

Access Ralph UI documentation locally:

npm run ralph-ui-docs

Developer CLI tools

Ralph Storefront includes helpful CLI commands:

Create new components:

npm run ralph-create

Creates a component file and SCSS file in the correct folder structure based on the Atomic Design pattern.

Override Ralph UI components:

npm run ralph-ride

Override existing components or styles from Ralph UI. Choose to override only styles or the full component.

Generate image sizes:

npm run ralph-image-sizes

Generate the config/image-sizes.csv file from your image configuration for import into the Geins image scaling service.

Repository structure

Ralph Storefront follows a clean, organized structure:

ralph-storefront/
├── app/                    # Core application code
├── assets/                 # Logos, fonts, icons, and static assets
├── components/             # Vue components organized by Atomic Design
│   ├── atoms/              # Basic building blocks
│   ├── molecules/          # Combined components
│   └── organisms/          # Complex component groups
├── config/                 # Configuration files
│   ├── channel-settings.js # Channel-specific settings
│   ├── image-sizes.json    # Image size configuration
│   └── route-paths.js      # Route path configuration
├── languages/              # i18n translation files
├── layouts/                # Nuxt layouts
├── middleware/             # Nuxt middleware
├── pages/                  # Nuxt pages
├── static/                 # Static files (favicon, meta images, mail assets)
├── store/                  # Vuex store modules
├── styles/                 # SASS styles (BEM methodology)
│   ├── variables/          # SASS variables
│   ├── global/             # Global styles
│   └── helpers/            # Helper styles
├── nuxt.config.js          # Nuxt configuration
├── .env.example            # Environment variables example
└── Dockerfile              # Docker configuration

This structure promotes:

• Clear separation of concerns - Components, pages, layouts, and configuration are clearly separated
• Scalability - Organized structure makes it easy to add new features
• Maintainability - Consistent patterns make code easier to understand and modify
• Developer experience - Logical organization helps developers find what they need quickly

Technology stack

Ralph Storefront is built with modern, production-ready technologies:

Core technologies

• Nuxt.js - Vue.js framework for universal applications with server-side rendering
• Vue.js - Progressive JavaScript framework for building user interfaces
• GraphQL - Query language for APIs providing efficient data fetching
• Apollo - GraphQL client for state management and data fetching

Styling & Design

• SASS - CSS preprocessor for maintainable stylesheets
• BEM methodology - Block Element Modifier naming convention for CSS
• Feather Icons - Beautiful, customizable icon set

Development tools

• ESLint - Code linting and formatting
• Prettier - Code formatting
• Stylelint - CSS/SASS linting

Extension modules

Extend Ralph Storefront's capabilities with specialized modules available on npm. Ralph modules are built on top of Ralph and can be installed via npm to elevate your customer experience.

Available modules

You can find all Ralph modules on npm. Here are the available modules:

Installation

Install any module via npm:

npm install @geins/ralph-module-gtm

Configuration & Customization

Channel settings

Configure channel-specific settings in config/channel-settings.js:

export const channelSettings = [
  {
    channelId: '1|se',
    siteName: 'Ralph Storefront', // Change to your store name
    theme: {
      'accent-color': '#131313', // Your brand color
      // Add more theme variables here
    },
  },
];

All variables in the theme property convert to global CSS variables and can be used throughout the application.

Runtime configuration

Extensive runtime configuration in nuxt.config.js allows you to customize:

• Global settings - Base URL, API endpoints, fallback markets, breakpoints
• Product lists - Default sorting, page sizes, filter options
• Product pages - Image ratios, stock limits, schema options, related products
• Checkout - Payment methods, shipping options, multi-market support
• Cart - Quantity changers, product image sizes
• Customer types - B2C, B2B, wholesale configurations
• CMS/Widgets - Banner colors, product list widgets, image sizes

Design customization

Customize your store's appearance:

1. Add assets - Replace logos, fonts, favicon, and meta images in assets/ and static/ folders
2. Update styles - Modify variables in styles/variables/, global styles in styles/global/, and helpers in styles/helpers/
3. Configure themes - Set brand colors and theme variables in channel settings
4. Add icons - Include custom icons in assets/icons/ and use with the CaIcon component

All styles use SASS and follow the BEM methodology for maintainability.

Notes

Ralph Storefront represents years of e-commerce development experience distilled into a production-ready template. The architecture emphasizes:

• Developer productivity - CLI tools, hot reload, and organized structure accelerate development
• Performance - PWA support, optimized images, and server-side rendering ensure fast load times
• Flexibility - Override any component, customize any configuration, or extend with custom features
• Best practices - Atomic Design, BEM methodology, and TypeScript support promote maintainable code
• Future-proof - Built on modern, actively maintained technologies with regular updates

The launchpad is actively maintained with regular updates, new features, and improvements. Check the CHANGELOG.md for detailed release notes.