Adding external CSS libraries

If you want to use external CSS libraries you can install them using NPM and include the necessary files.

Bootstrap

1. Install the dependency: npm install bootstrap
2. Use the distributable, either:
   • Include it in the stylus entry file patterns/index.styl (preferred):
     @import 'node_modules/bootstrap/dist/css/bootstrap.css'
   • Import directly in the application entry file pages/_app.js:
     import 'bootstrap/dist/css/bootstrap.css'

IE11 Compatability

By default, this application is not supporting IE11. Therefore, we have a middleware in server/index.js that detects if a user is coming with IE and if so, we render a page which suggests downloading a modern browser.

If you need to support IE11, you have to remove this middleware. In addition, there are a couple of APIs and features that you will need to polyfill or refactor:

CSS Custom Properties

The application makes heavy use of CSS Custom Properties. In order to add a fallback for IE11, you will need to perform the following steps:

• npm install postcss-css-variables
• Create a postcss.config.js and add:

module.exports = {
  plugins: {
    'postcss-css-variables': {
      preserve: true, // set this to false if you don't need custom properties at runtime
    },
  },
}

Error: listen EADDRINUSE: address already in use :::5000

Sometimes it might happen that you get this error in your console while trying to start the Storefront. This can have multiple reasons. The most common is that you already have a Storefront running on that port and forgot to
stop the process properly. In that case: Just stop the Storefront that already runs on that port. If the terminal of that process isn't open anymore or stopping the process doesn't work you can try this:

lsof -i tcp:5000
kill -9 PID

netstat -ano | findstr :5000
tskill typeyourPIDhere

macOS Monterey

If, after updating to macOS Monterey, you're facing this error message while trying to start the Storefront Error: listen EADDRINUSE: address already in use :::5000 check out this thread.

Image handling

Introductions

When you use the Page Editor and Storefront, you can automatically adjust images on the spot for faster loading. These resized images get saved in a CDN, making the delivery even quicker. The storefront has this feature built-in, and you just need to make a few simple settings to activate it.

Technical Instruction

To use image transformations in the storefront, follow these steps:

1. Change the MAKAIRA_ASSET_URL in your settings to https://<customer>.makaira.media*(where is the same as the subdomain in your MAKAIRA_API_URL).
2. Now, you can apply transformations using either the main <Image /> component or the getImageLink function from useConfiguration. The <Image /> component lets you display the image with different sizes based on CSS media queries, while the getImageLink function gives you the URL of the transformed image.
3. In both cases, you can provide transformations using an object called options. This object should include at least the source field, which contains the image path (without the domain), and other transformation details like width or quality. The default configuration supports various transformations, including:
   • width
   • height
   • quality
   • dpr
   • fit
   • trim
   • background
   • rotate
   • blur
   • border
   • brightness
   • compression
   • contrast
   • gamma
   • sharpen
   • gravity

For a full list of the default transformations, check https://developers.cloudflare.com/images/image-resizing/resize-with-workers/#fetch-options

Examples

Image Rendering

Rendering an image with various sizes for different viewports. Remember, the order of the options matters – the one with the key desktop or listed first will be the fallback source.

<Image
  alt='Alt Text'
  options={{
    desktop: {
      source: "image123.jpg",
      width: 768,
      media: '(min-width: 768px)',
    },
    mobile: {
      source: "image123.jpg",
      width: 480,
      media: null,
    },
  }}
/>

Image URL generating

Obtaining the transformed image URL according to options

const { getImageLinks } = useConfiguration()
const imageLink = getImageLink({
source: "image123.jpg",
width: 500,
})

Limitations

Because of technical limitations, the format transformation is currently not supported. It will get supported in the future. Also, the AVIF file format is not supported as an import format.

Other media transformation provider

Like the included image transformation method, you can also use Cloudinary with the same API described above. However, keep in mind that Cloudinary offers advanced transformations, which are beyond basic ones like width, height, format, or quality, and these may not be compatible with the default image transformation provided by makaira.media.