如何将仅客户端npm包导入qwikify$组件？解决document未定义错误

问题根源 #

你的代码中，顶层的import ReactQuill from 'react-quill'会在服务端渲染（SSR）阶段被执行，而Quill库的源码直接依赖浏览器的document对象，Node.js环境中不存在这个对象，因此触发报错。即使设置了qwikify$的clientOnly: true，模块导入操作早于组件渲染，服务端仍会加载Quill的代码。

解决方案：延迟客户端导入 #

通过动态导入确保Quill相关代码仅在浏览器环境中加载，避免SSR阶段执行。

完整代码示例 #

import { component$, useClient$ } from '@builder.io/qwik';
import { qwikify$ } from '@builder.io/qwik-react';
import { useState } from 'react';

export default component$(() => {
  // 仅在客户端环境中加载并初始化ReactQuill组件
  const QuillEditor = useClient$(() => {
    // 动态导入react-quill核心库
    const ReactQuill = require('react-quill').default;
    // 导入Quill样式（按需选择主题）
    require('react-quill/dist/quill.snow.css');

    // 创建qwik化的React组件
    const QwikQuill = qwikify$(() => {
      const [value, setValue] = useState('');
      return <ReactQuill theme="snow" value={value} onChange={setValue} />;
    }, { clientOnly: true });

    return QwikQuill;
  });

  // 渲染客户端组件
  return <QuillEditor />;
});

关键步骤说明 #

• 使用useClient$隔离客户端代码：useClient$内的代码只会在浏览器中执行，完全避开SSR阶段。
• 动态导入Quill库：通过require（或import()）在客户端按需加载react-quill及其样式，避免服务端解析时触发document访问。
• 在客户端内完成qwikify转换：确保整个ReactQuill组件的初始化流程都在浏览器环境中进行。

替代方案：React.lazy + Suspense #

如果更习惯React的写法，也可以结合React.lazy和Suspense实现延迟加载：

/** @jsxImportSource react */
import { qwikify$ } from '@builder.io/qwik-react';
import { lazy, Suspense, useState } from 'react';

// 动态导入ReactQuill，仅在组件渲染时加载
const ReactQuill = lazy(() => import('react-quill'));

const MyReactQuillComponent = () => {
  const [value, setValue] = useState('');
  // 客户端导入样式
  import('react-quill/dist/quill.snow.css');

  return (
    <Suspense fallback={<div>加载编辑器中...</div>}>
      <ReactQuill theme="snow" value={value} onChange={setValue} />
    </Suspense>
  );
};

export default qwikify$(() => <MyReactQuillComponent />, { clientOnly: true });

这种方式依赖React的懒加载机制，确保Quill代码仅在客户端渲染时加载，同样能避开SSR的document问题。

内容的提问来源于stack exchange，提问作者meightythree