在NextJS项目中集成Shoelace组件库的完整指南

袁耿浩

于 2025-06-03 09:02:10 发布

阅读量265

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00841/article/details/148392043

在NextJS项目中集成Shoelace组件库的完整指南

shoelace A collection of professionally designed, every day UI components built on Web standards. Works with all frameworks as well as regular HTML/CSS/JS. 🥾 项目地址: https://gitcode.com/gh_mirrors/sh/shoelace

Shoelace是一个现代化的Web组件库，提供了丰富的UI组件和良好的设计系统。本文将详细介绍如何在NextJS项目中集成Shoelace组件库，涵盖App Router和Pages Router两种架构模式。

前置准备

在开始集成前，需要确保你的开发环境满足以下要求：

Node.js版本：v16+（推荐v20+）
NextJS版本：12+（推荐14+）
Shoelace版本：2.0+

方案一：App Router集成（NextJS 14+）

1. 项目初始化与配置

首先创建一个新的NextJS项目，然后在package.json中添加ESM支持：

{
  "type": "module"
}

2. 安装依赖

安装Shoelace核心库和Webpack插件：

npm install @shoelace-style/shoelace copy-webpack-plugin

3. 配置NextJS

修改next.config.js文件，添加Webpack配置以处理Shoelace资源：

import { dirname, resolve } from 'path';
import { fileURLToPath } from 'url';
import CopyPlugin from 'copy-webpack-plugin';

const __dirname = dirname(fileURLToPath(import.meta.url));

const nextConfig = {
  experimental: { esmExternals: 'loose' },
  webpack: (config) => {
    config.plugins.push(
      new CopyPlugin({
        patterns: [
          {
            from: resolve(__dirname, 'node_modules/@shoelace-style/shoelace/dist/assets/'),
            to: resolve(__dirname, 'public/shoelace-assets/assets/')
          }
        ]
      })
    );
    return config;
  }
};

export default nextConfig;

这个配置会将Shoelace的静态资源复制到项目的public目录下。

4. 全局样式设置

在app/layout.tsx中引入Shoelace的默认主题：

import '@shoelace-style/shoelace/dist/themes/light.css';

5. 创建Shoelace初始化组件

创建app/shoelace-setup.tsx组件来设置基础路径：

'use client';
import { setBasePath } from "@shoelace-style/shoelace/dist/utilities/base-path.js"

export default function ShoelaceSetup({ children }) {
  setBasePath(`/shoelace-assets/`);
  return <>{children}</>
}

然后在根布局中包裹这个组件：

import ShoelaceSetup from "./shoelace-setup";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <ShoelaceSetup>
          {children}
        </ShoelaceSetup>
      </body>
    </html>
  );
}

6. 使用Shoelace组件

在页面组件中，使用NextJS的动态导入来加载Shoelace组件：

'use client';
import dynamic from 'next/dynamic';

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

export default function Home() {
  return <SlButton>Click Me</SlButton>;
}

方案二：Pages Router集成（NextJS 12+）

1. 安装额外依赖

npm install @shoelace-style/shoelace copy-webpack-plugin next-compose-plugins next-transpile-modules

2. 启用ESM支持

在package.json中添加：

{
  "type": "module"
}

3. 导入主题样式

在_app.js中引入主题：

import '@shoelace-style/shoelace/dist/themes/light.css';

4. 创建自定义元素加载器

function CustomEls({ URL }) {
  const customEls = useRef(false);

  useLayoutEffect(() => {
    if (customEls.current) return;
    
    import('@shoelace-style/shoelace/dist/utilities/base-path').then(({ setBasePath }) => {
      setBasePath(`${URL}/static/static`);
      import('@shoelace-style/shoelace/dist/react');
      customEls.current = true;
    });
  }, [URL]);

  return null;
}

5. 条件渲染组件

在_app.js中：

function MyApp({ Component, pageProps, URL }) {
  const isBrowser = typeof window !== 'undefined';
  return (
    <>
      {isBrowser && <CustomEls URL={URL} />}
      <Component {...pageProps} />
    </>
  );
}