NextJS integration tutorial and docs doesn't work

[tomerlichtash]

Describe the bug

NextJS integration tutorial doesn't seem to be working. It provides an example repo, which doesn't seem to be working as well.

While trying several configurations, seems like NextJS is running into an error:

ReferenceError: MutationObserver is not defined

So, MutationObserver is not available for the Node env.

To Reproduce

Steps to reproduce the behavior:

1. Clone https://github.com/crutchcorn/nextjs-shoelace-example or follow instructions on Integrating with NextJS
   
2. Run npm i
3. run npm run dev
4. See error

Screenshots

Browser / OS

• OS: Mac M1
• Browser: All browsers

[tomerlichtash]

Also followed this method with dynamic importing - which worked in dev env, although error was reproduced.
However, the app could run after build, for same error.

[tomerlichtash]

Some progress: Managed to get the dynamic import approach (provided above) to work. Problem was that .env.development had precedence and was missing the BASE_URL var.

Still, could not get the official tutorial method to work, though.

[claviska]

Hi there! These tutorials have been contributed by the community. We're working on getting some officially maintained ones up, but we're a small team with a lot happening so please be patient. In the meantime, feel free to PR updates if you make any progress here!

[andrico1234]

Hi Cory,

I've come across the same issue in a SvelteKit app. It happens when I import Shoelace's button.js module on a server environment.

I created a repro case here: https://github.com/andrico1234/shoelace-ssr-repro

I also created a Loom running through the problem in more detail: https://www.loom.com/share/721320086a7b49f7b9873e0a9ae53642

In short, my solution is to check whether I'm in a browser environment in SvelteKit and then dynamically import the button.

Before

<script>
  import "@shoelace-style/shoelace/dist/themes/light.css";
  import "@shoelace-style/shoelace/dist/components/button/button.js";
</script>

<sl-button>Hey there</sl-button>

After

<script>
  import "@shoelace-style/shoelace/dist/themes/light.css";
  import { browser } from "$app/environment";

  if (browser) {
    import("@shoelace-style/shoelace/dist/components/button/button.js");
  }
</script>

<sl-button>Hey there</sl-button>

I also ran the build step and previewed the production bundle with my solution and the button renders as expected.

I have a few questions with my workaround:

1. Are there any concerns with using a dynamic import to load a Shoelace component? My first guess is that there's not, aside from some FOUC
2. Is there a better way of handling SSR in Shoelace? If not, and this is a good enough approach, then I'd be happy to contribute something to the documentation.
3. The if (browser) check works in SvelteKit, but not every SSR environment will have an equivalent flag. Is there a more general check you recommend, particularly if I wanted to handle this in a library that could be used in any framework?

Thanks for the great library!

[claviska]

SSR is still on our radar. We have some work to do to get it working with Lit's SSR module. I've opened a new issue to track where we're planning on going with this: #1718

Please subscribe to that issue for updates.

[willpinha]

@andrico1234 Thanks! I was having the same problem with SvelteKit, and using browser conditionals solved it for me

@claviska Maybe while #1718 is not finished, add SvelteKit installation docs in the Tutorials

[royeradames]

This doesn't solve the issue. This issue encounter when running the build script

installing the npm package and making sure you are importing from dist and not cdn doesn't solve this issue.

(outdated) Solving import issue: (Next.js 14+ [App])

Need to check that it works in production
Need to check the limitations in unit, and end to end testing

npm install @shoelace-style/shoelace

on your root layout add the .css styles import

add this to your package jason

  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@shoelace-style/shoelace/*": ["cdn/react/*"]
    },
    "typeRoots": ["./node_modules/@types", "./cdn/react"]
  },
  "include": ["src", "cdn/react"],

See if this helps out

[royeradames]

I think we are encountering a similar issue like High chart

https://github.com/highcharts/highcharts-react#highcharts-with-nextjs

But for us do to use importing many components. It doesn't seen to be a clean solution

[royeradames]

Dynamic import seen to be the solution

Working on a implementation

https://nextjs.org/docs/pages/building-your-application/optimizing/lazy-loading#with-no-ssr

[royeradames]

Working solution with dynamic import

The correct way to import shoelace component is next.js

SlTab can be replace with the React name of the sl element

const SlTab = dynamic(
  () => import("@shoelace-style/shoelace/dist/react").then(mod => mod.SlTab),
  {
    ssr: false,
  }
)

Avoid build issues.

[KonnorRogers]

I dont recommend using the top level entrypoint. It will import every component.

I would just import the component directly.

const SlTab = dynamic(
  () => import("@shoelace-style/shoelace/dist/react/tab/index.js"),
  {
    ssr: false,
  }
)

[KonnorRogers]

There's some new docs for NextJS app router here if anyone has a moment and would like to check them out:

#2096