Advice for build using ES6 modules

[lutuh]

Hello Máximo,

I've found the way to îles via your appeareance on the Views on Vue podcast (https://viewsonvue.com/islands-architecture-in-vue-with-m-ximo-mussini-vue-170) and I'm currently poking around and checking feasibility for an upcoming project. Iles is great! Lots of stuff to learn for a backend dev like me.

I tried integrating an image gallery named Photoswipe (https://photoswipe.com/v5/docs/getting-started/). This is easy and works fine. When building the project though, the iles SSG said:

Error [ERR_REQUIRE_ESM]: require() of ES Module /home/baxter/source/iles-play/node_modules/photoswipe/dist/photoswipe-lightbox.esm.js from /home/baxter/source/iles-play/.iles-ssg-temp/assets/default.a6095cd9.js not supported.
Instead change the require of photoswipe-lightbox.esm.js in /home/baxter/source/iles-play/.iles-ssg-temp/assets/default.a6095cd9.js to a dynamic import() which is available in all CommonJS modules.
    at Module.<anonymous> (/home/baxter/source/iles-play/.iles-ssg-temp/assets/default.a6095cd9.js:24:26)
    at /home/baxter/source/iles-play/.iles-ssg-temp/assets/index.0d1bd837.js:289:10
    at async resolveLayout (/home/baxter/source/iles-play/.iles-ssg-temp/app.js:292:54) {
  code: 'ERR_REQUIRE_ESM'
}

Photoswipe is installed via npm install --save git://github.com/dimsemenov/photoswipe#v5-beta and imported as usual:

import PhotoSwipeLightbox from 'photoswipe/dist/photoswipe-lightbox.esm.js'
import PhotoSwipe from 'photoswipe/dist/photoswipe.esm.js'

What I've tried

I went and started learning about the different module systems in JS and how bundlers work. I now know that the package I want to use is a ES6 module and that the iles SSR somehow does not like it. Not sure why, though. I tried renaming the files from .esm.js to .mjs as well as using the const PhotoSwipe = await import('photoswipe/dist/photoswipe.esm.js') syntax, no dice.

I tried importing and building in the Vue3 + Vite starter template with success. So I think that this is not Vite-related. It might be obvious to you, but I am kinda stuck at this point.

Reproduction

Thank you very much for pointing me into the right direction on how to properly include an ES6 module in the build. In case you want to reproduce the error, that should be quite easy:

$ npm init iles@next + follow steps in npm output
$ npm install --save git://github.com/dimsemenov/photoswipe#v5-beta

Append to <script setup lang="ts"> in src/components/HelloWord.vue:

import PhotoSwipeLightbox from 'photoswipe/dist/photoswipe-lightbox.esm.js'
import PhotoSwipe from 'photoswipe/dist/photoswipe.esm.js'

const lightbox = new PhotoSwipeLightbox({
  gallery: '#my-gallery',
  children: 'a',
  pswpModule: PhotoSwipe
});
lightbox.init();
console.log(lightbox)

Then build

$ iles build

Thank you very much!
Lucas

[ElMassimo]

Hi Lucas! @lutuh

Vite relies on modern practices to detect whether a package is CJS or ESM, or both, and performs certain optimizations (like pre-bundling during dev, or external during SSR), to ensure it's loaded in the more efficient way.

Package Problem

It seems that this package has not been updated to use [recent practices to be compatible with CJS and ESM at the same time.

For example, it does not supply the exports field (nor the module field as a fallback), and it does not have "type": "module".

In addition, the main entry it supplies, does not exist.

Solution

Fork (or make a PR) to add the exports field to the package.json:

  "type": "module",
  "exports": {
    ".": "./dist/photoswipe.esm.js",
    "./lightbox": "./dist/photoswipe-lightbox.esm.js"
  },

Alternatively, you can look for a different package that has been updated to support ESM/CJS.

---

The following is something that you might find useful given the kind of library that you are trying to import, but feel free to ignore for now.

Accessing the DOM Problem

Since this particular package uses the DOM directly (document), it can not run in node during build, so you need to make sure to only import it in the client-side. Otherwise:

function getElementsFromOption$1(option, legacySelector, parent = document) {
                                                                  ^

ReferenceError: document is not defined

Solution

You can use a dynamic import behind a condition that checks the import.meta.env flags provided by Vite.

// Runs only in the client, not when rendering pages during the build
if (!import.meta.env.SSR) {
  const PhotoSwipeLightbox = (await import('photoswipe/lightbox')).default
  const lightbox = new PhotoSwipeLightbox({ ... })
}

However, in this case using onMounted would be more convenient (components are not mounted during SSR):

import { onMounted } from 'vue'

onMounted(async () => {
  const PhotoSwipeLightbox = (await import('photoswipe/lightbox')).default
  const PhotoSwipe = (await import('photoswipe')).default

  const lightbox = new PhotoSwipeLightbox({
    gallery: '#my-gallery',
    children: 'a',
    pswpModule: PhotoSwipe
  });
  lightbox.init();
  console.log(lightbox)
})

Since you are asking in the context of îles, it's likely that you want this to be interactive.

To do that, you can use onMounted inside a Vue island, or just use a client script in a non-Vue component of your choice:

<script client:load lang="ts">
import PhotoSwipeLightbox from 'photoswipe/lightbox'
import PhotoSwipe from 'photoswipe'

export function onLoad (el) {
  const lightbox = new PhotoSwipeLightbox({
    gallery: '#my-gallery',
    children: 'a',
    pswpModule: PhotoSwipe
  });
  lightbox.init();
  console.log(lightbox)
}
</script>

[lutuh]

Hello Máximo,

now it all comes together. Thank you so much for your detailed and structured response!

I've been playing with "type": "module" in the package.json and also hit the ReferenceError: document is not defined error. It feels good to be able to understand these things a bit better.

The code is already running in an island Vue component (via client:visible). I used dynamic imports in the onMounted hook as you suggested and it works!

Making the lightbox accessible from the template was easy using a reactive variable:

let lightbox = ref(null)

onMounted(async () => {
  ...
  lightbox.value = new PhotoSwipeLightbox({
    ...
  })
  lightbox.value.init()
})

Thanks again!

Lucas