Configuration for your launchpad

In short; everything is set up for you. You can start building your store right away. This launchpad also comes with a test drive payment gateway and a freight checkout. This means that you can test your store right out-the-box without having to set up a payment gateway or freight provider.

General setup

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.

Tip

If you want to run your store with a multi market setup (with /market/language in the url), then just remove the DOMAINS variable and your site will default to multi market.

Variable	Description	Required	Example value
`API_ENDPOINT`	The API endpoint for your Geins Merchant API	Yes	`https://url.com`
`API_KEY`	Your Geins Merchant API key	Yes	`00000000-0000-0000-0000-000000000000`
`AUTH_ENDPOINT`	The auth endpoint for your Geins Merchant API	Yes	`https://url.com`
`SIGN_ENDPOINT`	The sign endpoint for your Geins Merchant API	Yes	`https://url.com`
`BASE_URL`	The base URL for your store including http/https without ending slash	Yes	`https://url.com`
`FALLBACK_CHANNEL_ID`	The fallback channel ID for your store	Yes	`1ǀse`
`FALLBACK_MARKET_ALIAS`	The fallback market alias for your store	Yes	`se`
`DEFAULT_LOCALE`	The default locale for your store	Yes	`sv`
`RALPH_ENV`	The environment for your store (dev, qa or prod)	No	`dev`
`DOMAINS`	The domains for your store (if you want to use different domains for different languages/markets)	No	`svǀwww.site.se,fiǀwww.site.fi`

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.

Nuxt config

In the Nuxt config file nuxt.config.js you can set up most things, for example routes configuration and your runtime config (global variables that are accessed through the $config object). Please refer to the Nuxt Configuration Glossary for more information. We will dive deeper into our Nuxt config setup further down this page.

Channel settings

You will find some channel settings in config/channel-settings.js. This is a good place to set up and add variables that differs between channels. All variables added to the theme property will get converted into global CSS variables and can be used throughout the application. The channel settings are imported into the Nuxt config file as currentChannelSettings and can be used for setup there. This below is the default setup for the channel settings.

config/channel-settings.js
export const channelSettings = [
  {
    channelId: '1|se',
    siteName: 'Ralph Storefront', // Change this to the name of your store
    theme: {
      'accent-color': '#131313', // Change this to yours
      // Add more theme variables here if you like
    },
  },
];

Design setup

Assets

Add your desired logos and fonts etc to the assets folder. In the static folder, you should replace the favicon.ico, icon.png and the meta-image-fallback.jpg with your own. Here is also where you can add assets for your Geins generated emails, in the static/mail folder.

Icons

By default, the project comes with a set of icons from Feather Icons in the assets/icons folder. You can use these icons throughout the application, for example by using the CaIcon component. You can also add your own icons to this folder. To decrease the size of the site bundle, only the icons that are actively used in the project are included in the assets/icons folder. The rest of the icons you can find in the assets library folder in the root of the project.

Styles

In the styles folder, you'll find all the styles for the application. For the general setup, it is suggested to look through and adjust the files in the styles/variables folder, and also the styles/global and the styles/helpers folders.

All styles are written in SASS, and the styles are structured according to the BEM methodology.

Image sizes

To understand how to configure image sizes you will first need to have knowledge of how to work with the HTML img elements' sizes and srcset attributes. If you are not familiar with these attributes, you can read more about them here.

By default your project comes with a bunch of already configured image sizes. Most often you will not even have to change anything and can just roll with the pre-configured sizes.

If you do want to change for example the aspect ratio of your product images or add/remove image sizes, read more further down where we get more into detail about image sizes.

Nuxt.config.js

Here follows a guide on the most important parts of the nuxt.config.js file.

Internationalization (`i18n`)

In the i18n object, you can set up the internationalization settings for the project.

Languages

By default, the project comes with English, Swedish, Norwegian, Danish and Finnish. If you are not gonna use all of these languages, you should remove the ones you're not using from the locales array. If you want to add another language, add it to the array and create a new file in the languages folder with the same name as the language code.

nuxt.config.js
  return {
    ...
    i18n: {
      ...
      locales: [
        {
          code: 'en',
          iso: 'en-US',
          file: 'en-US.js',
          name: 'English',
          // Only used if you have multiple markets on DIFFERENT domains (using the DOMAINS env variable)
          domain: domainUrls?.en || '', 
        },
        ...
      ],
      ...

Pages

In the pages object of the i18n object, you can name your routes that you want translated. The key is the name of the route and the value is the translation key.

nuxt.config.js
  return {
    ...
    i18n: {
      ...
      pages: {
        'checkout/index': {
          en: '/checkout',
          sv: '/kassan',
        },
        ...
      },
      ...

The default setup comes with a bunch of translated routes for all the languages. You can remove the ones you're not gonna use.

PWA settings & loading bar

The PWA settings are used to configure the PWA. You can change the name, description and theme color of the PWA. This gives your store the look and feel of your brand. By default this is set from what your channel settings, but you can change it here if you like.

nuxt.config.js
  return {
    ...
    // Loading bar color
   loading: {
      color: currentChannelSettings.theme['accent-color'],
      height: '5px',
    },
    ...
    // PWA settings
    pwa: {
      manifest: {
        name: currentChannelSettings.siteName,
        short_name: currentChannelSettings.siteName,
        description: fallbackMeta.description,
        theme_color: currentChannelSettings.theme['accent-color'],
      },
      ...
    },
    ...

Router settings

The router settings are used to configure your routes. This launchpad comes with all the routes you need to get started. Although, you might need to add some own custom routes for your project, and this is where you do it.

nuxt.config.js
  return {
    ...
    router: {
    ....
     extendRoutes(routes, resolve) {
      ...
      routes.push({
          name: 'my-custom-page',
          path: '/my-custom-path',
          component: resolve(__dirname, 'pages/custom/my-page.vue'),
        });
     }
    ...

Runtime config (`publicRuntimeConfig`)

The runtime config is used to set up global variables that can be accessed throughout the application. This is where you set up the most important settings for your store.

Global settings

Setting	Description	Default value	Type
`ralphLog`	Settings for when to debug log different messages to the console	`{ onlyInClient: true, all: ralphEnv === 'dev', api: false, events: false, checkout: false, warnings: false }`	Object
`ralphEnv`	The environment for your store, by default not used by anything apart from setting `ralphLog`, but could be useful	`process.env.RALPH_ENV` or `prod`	String
`baseUrl`	The base URL for your store including https:// and without ending slash	`process.env.BASE_URL`	String
`imageServer`	The image server url	`process.env.IMAGE_SERVER`	String
`authEndpoint`	The auth endpoint url	`process.env.AUTH_ENDPOINT`	String
`signEndpoint`	The sign endpoint url	`process.env.SIGN_ENDPOINT.replace('{API_KEY}', process.env.API_KEY)`	String
`apiKey`	The API key for your store	`process.env.API_KEY`	String
`apiEndpoint`	The API endpoint for your store	`process.env.API_ENDPOINT`	String
`fallbackChannelId`	The fallback channel ID for your store	`process.env.FALLBACK_CHANNEL_ID`	String
`fallbackMarketAlias`	The fallback market alias for your store	`process.env.FALLBACK_MARKET_ALIAS`	String
`currentChannelSettings`	The settings from `config/channel-settings.js` with the same id as `fallbackChannelId`	-	Object
`channelSettings`	All channel settings from `config/channel-settings.js`	-	Array
`fallbackMarkets`	All available markets fetched in `config/fallback-data.js`	-	Array
`imageSizes`	All available image sizes parsed in `config/image-sizes.js`	-	Array
`useStartPage`	NOTE! This has been removed from v23.0.0. Set this to true if you want to create a start page for selecting market/language in a multi market setup	`false`	Boolean
`customerServiceEmail`	The email for customer service	`[email protected]`	String
`customerServicePhone`	The phone number for customer service	`+46 123 23 43 45`	String
`breakpoints`	The breakpoints you want to use for your store	`{ tablet: 768, laptop: 1024, desktop: 1200, desktopBig: 1440 }`	Object
`siteTopThreshold`	The threshold in pixels for when `siteIsAtTop` getter should be `true`	`10`	Number
`socialMediaLinks`	The social media links for your store, can for example be used to render social media icons for the footer	`[{ icon: 'facebook', title: 'Facebook', link: 'https://www.facebook.com' }, { icon: 'instagram', title: 'Instagram', link: 'https://www.instagram.com' }]`	Array
`customerTypesToggle`	Set to true if you want to use the customer types feature	`true`	Boolean
`customerTypes`	The customer types you want to use	`[{ type: 'PERSON', vat: true }, { type: 'ORGANIZATION', vat: false }]`	Array
`routePaths`	The route paths setup in `config/route-paths.js`	`{category: '/c', brand: '/b', product: '/p', search: '/s', discountCampaign: '/dc', list: '/l'}`	Object
`statesToPersist`	The states of the store that you want to persist when page reloades. These states will be saved in a cookie called `ralph-persisted-states`	`['favorites', 'customerType', 'vatIncluded', 'list/relocateAlias', 'list/relocatePage']`	Array
`searchProductsImageSizes`	The image sizes attribute to use for the search products	`35px`	String

Setting	Description	Default value	Type
`bannerWidgetPrimaryColor`	The primary color for the banner widget	`#000000`	String
`bannerWidgetSecondaryColor`	The secondary color for the banner widget	`#FFFFFF`	String
`productListWidgetArrowIconName`	The name of the icon to use for the arrow in the product list widget	`chevron`	String
`productListRowSize`	The default number of products per row in the product list widget	`5`	Number
`widgetImageSizes`	The images `sizes` attribute for the different column sizes	`{ full: '(min-width: 1920px) 1920px, 97vw', half: '(min-width: 1920px) 950px, (min-width: 768px) 48vw, 97vw', third: '(min-width: 1920px) 627px, (min-width: 768px) 32vw, 97vw', quarter: '(min-width: 1920px) 465px, (min-width: 768px) 24vw, 97vw', }`	Object
`widgetImageSizesFullWidth`	The images `sizes` attribute for the different column sizes when the widget area container is set to full width	`{ full: '100vw', half: '(min-width: 768px) 49vw, 100vw', third: '(min-width: 768px) 33vw, 100vw', quarter: '(min-width: 768px) 24vw, 100vw' }`	Object

Product lists

Setting	Description	Default value	Type
`productListDefaultSort`	The default sorting for product lists	`LATEST`	String
`productListPageSize`	The default page size for product lists	`20`	Number
`productListScrollSize`	The number of products to scroll at a time when using the `CaProductListSlider`	`{ phone: 2, tablet: 3, laptop: 5, desktop: 5, desktopBig: 6 }`	Object
`showCategoryFilter`	Set to true if you want to show the category filter	`true`	Boolean
`showCategoryTreeViewFilter`	Set to true if you want to show the category filter as a tree view	`true`	Boolean
`showBrandsFilter`	Set to true if you want to show the brands filter	`true`	Boolean
`showSkuFilter`	Set to true if you want to show the SKU filter	`true`	Boolean
`showPriceFilter`	Set to true if you want to show the price filter	`true`	Boolean
`showDiscountFilter`	Set to true if you want to show the discount filter	`true`	Boolean
`customSortRoutes`	Use this to override `productListDefaultSort` for specific routes. Use the name of the route as `name`. Example: `[{name: 'bestsellers', sort: 'MOST_SOLD'}]`	`[]`	Array
`productCardBuyButton`	Set to true if you want to show the buy button on the product card in product lists	`false`	Boolean

Product

Setting	Description	Default value	Type
`productImageRatio`	The ratio for the product images. This is by default set in the `config/image-sizes.json` file	`1.25`	Number
`productStockFewLeftLimit`	The few left limit for stock to use in stock status	`6`	Number
`productSchemaOptions`	The options for the product schema, make sure to change the schemaImageSize to an existing size of your site	`{ productSkuLabelIsSize: false, productDescriptionField: 'text1', schemaImageSize: '1000f1250', extraOfferProperties: { itemCondition: 'https://schema.org/NewCondition' } }`	Object
`productShowRelated`	Set to true if you want to fetch and show related products on product detail page	`false`	Boolean
`showProductReviewSection`	Set to true if you want to show the product review section on the product detail page	`false`	Boolean
`showStarsInProductReviewForm`	Set to true if you want to show the stars in the product review form	`true`	Boolean
`preLoadedProductImageSizes`	The image sizes to preload for the product detail page	`['1000f1250']`	Array

Checkout

Setting	Description	Default value	Type
`checkout.promoCodes`	Accept promo codes on checkout	`true`	Boolean
`checkout.shippingAddress`	Add option to add separate shipping address when using `CaCheckoutInvoice`	`true`	Boolean
`checkout.identityNumber`	Add option to add identity number when using `CaCheckoutInvoice`	`true`	Boolean
`checkout.entryCode`	Add option to add entry code when using `CaCheckoutInvoice`	`true`	Boolean
`checkout.message`	Add option to add message when using `CaCheckoutInvoice`	`true`	Boolean
`checkout.defaultPaymentId`	The default payment method id	`23`	Number
`checkout.defaultShippingId`	The default shipping method id, needs to be set when `useInternalShipping` is set to `true`	`null`	Number
`checkout.showMultipleMarkets`	Set to `true` if you want to show the country selector step in checkout	`true`	Boolean
`checkout.useInternalShipping`	Set to `true` if you want to use the internal shipping method	`false`	Boolean

Cart

Setting	Description	Default value	Type
`cart.hiddenSkuValues`	Dont show selected value for sku with these values in cart	`['-', 'One size']`	Array
`cart.quantityChangerType`	Quantity changer type for items in cart. Options: `default`, `round`, `stacked`	`default`	String
`cart.productImageSizes`	The image sizes attribute for the products in the cart	`(min-width: 768px) 80px, 53px`	String

User

Setting	Description	Default value	Type
`user.gender`	Show user gender picker in 'my accounts' settings	`false`	Boolean
`user.country`	Show user country picker in 'my accounts' settings	`false`	Boolean

Getting more into detail

Customer types

If you want to use the customer types feature, you need to enable it and add the customer types. You can also enable or disable the VAT field for each customer type. Add the types you want to use according to set up in merchant center.

Tip

This feature is powerful and can be used to create different customer groups. For example, you can create a customer type for wholesale customers and a customer type for retail customers. You can then use this feature to create different prices for each customer type.

nuxt.config.js
  return {
    ...
    publicRuntimeConfig: {
    ...
      customerTypesToggle: true,
      customerTypes: [
        {
          type: 'Retail',
          vat: true
        },
        {
          type: 'Wholesale',
          vat: false
        }
        ...

Image sizes

There are two parts of the image sizes set up. First, we need to provide a range of image sizes to feed the srcset attributes of all images. Then, we need to specify the sizes attributes for all the different places where images appears.

`srcset` attributes

In the config/image-sizes.json file (since Ralph Storefront v2.5.0+), you can set up what type of images you want to be available to use. When this is set up, you can use the npm run ralph-image-sizes to generate the config/image-sizes.csv file. This generated csv file is formatted to be imported into the image size table, which is used by our image scaling service.

During the build of the storefront, the csv file will be parsed and all available image sizes will be saved to the $config.imageSizes object, where the keys will be the type of image. So to feed a CaImage component with the available image sizes for a product, you can use the $config.imageSizes.product array in the sizeArray prop and the component will generate the full srcset attribute for you.

`sizes` attributes

When you have provided all available image sizes for the srcset attributes, you can set up the sizes attribute for all the different places where images appears. This is done differently depending on what image you want to specify sizes for.

If you're straight up using the CaImage component, you can use the sizes prop to specify the sizes string for the image. For the CaProductGallery they are set in mainImagSizes and thumbnailImageSizes props. For the CMS you can set all sizes attributes for different column widths in the widgetImageSizes object in the runtime config.

nuxt.config.js
  return {
    ...
    publicRuntimeConfig: {
    ...
      widgetImageSizes: {
        full: '(min-width: 1920px) 1920px, 97vw',
        half: '(min-width: 1920px) 950px, (min-width: 768px) 48vw, 97vw',
        third: '(min-width: 1920px) 627px, (min-width: 768px) 32vw, 97vw',
        quarter: '(min-width: 1920px) 465px, (min-width: 768px) 24vw, 97vw',
      },
      ...
    }

Image types

The type / folder is used in tha CaImage property type and as the key in the $config.imageSizes object. The name is used in the config/image-sizes.json file.

Name	Type / Folder	Description
product	product	Product images
cms	pagewidget	CMS images
category	categoryheader	Category images (Deprecated)
brand	brand	Brand images (Deprecated)

Using `config/image-sizes.json`

This file consists of an array of objects where each object represents an image type and sizing instructions. You can add more than one object with the same type.

Example

The settings below will set up product image sizes from the width of 100px to 2000px with an aspect ratio of 4:5. This will give you a set of images like 100x125px, 200x250px, 300x375px and so on.

For the CMS images, it is set to scale an image on every 100 pixels from 100px to 1000px and then every 500 pixels from 1500px to 4000px with the original aspect ratio. This will result in images with widths like 100px, 200px, 300px and so on for the first set and 1500px, 2000px, 2500px and so on for the second set.

config/image-sizes.json
{
  "imageSizes": [
    {
      "type": "product",
      "aspectRatio": "4:5",
      "startWidth": 100,
      "endWidth": 2000,
      "resizeFunction": "f",
      "incrementStep": 100
    },
    {
      "type": "cms",
      "aspectRatio": "",
      "startWidth": 100,
      "endWidth": 1000,
      "resizeFunction": "w",
      "incrementStep": 100
    },
    {
      "type": "cms",
      "aspectRatio": "",
      "startWidth": 1500,
      "endWidth": 4000,
      "resizeFunction": "w",
      "incrementStep": 500
    }
  ]
}

Here follows a detailed description of the properties of the objects in the config/image-sizes.json file:

Property	Description	Type
`type`	Provide the "Name" from the image type table above	String
`aspectRatio`	The aspect ratio of the image. If you want to keep the original aspect ratio, leave this empty. Must be in format "0:0"	String
`startWidth`	The smallest width you want the image to be resized to in pixels	Number
`endWidth`	The largest width you want the image to be resized to in pixels	Number
`resizeFunction`	The function to use for resizing. `f` is used to not crop but fill with white, `c` is used to crop from center, `x` is used to crop from top and `w` is used to only resize width, keeping the relative height	String
`incrementStep`	The step to increment the image width with on each row	Number

When you have set up the config/image-sizes.json file, you can run the npm run ralph-image-sizes command to generate the config/image-sizes.csv file.

Next step: Working with Components

Now that you have set up your configuration, you can start working with the components in your store. Head over to the Components section to learn more about the components in this launchpad.

Configuration for your launchpad

General setup​

Environment variables​

Nuxt config​

Channel settings​

Design setup​

Assets​

Icons​

Styles​

Image sizes​

Nuxt.config.js​

Internationalization (i18n)​

Languages​

Pages​

PWA settings & loading bar​

Router settings​

Runtime config (publicRuntimeConfig)​

Global settings​

CMS / Widget settings​

Product lists​

Product​

Checkout​

Cart​

User​

Getting more into detail​

Customer types​

Image sizes​

srcset attributes​

sizes attributes​

Image types​

Using config/image-sizes.json​

Next step: Working with Components​

General setup

Environment variables

Nuxt config

Channel settings

Design setup

Assets

Icons

Styles

Image sizes

Nuxt.config.js

Internationalization (`i18n`)

Languages

Pages

PWA settings & loading bar

Router settings

Runtime config (`publicRuntimeConfig`)

Global settings

CMS / Widget settings

Product lists

Product

Checkout

Cart

User

Getting more into detail

Customer types

Image sizes

`srcset` attributes

`sizes` attributes

Image types

Using `config/image-sizes.json`

Next step: Working with Components