#ctx.libs

ctx.libs는 RunJS 내장 라이브러리의 통합 네임스페이스이며, React, Ant Design, dayjs, lodash 등 자주 사용되는 라이브러리를 포함하고 있습니다. import나 비동기 로드가 필요 없으며, ctx.libs.xxx를 통해 직접 사용할 수 있습니다.

#적용 시나리오

#내장 라이브러리 목록

#최상위 별칭(Alias)

기존 코드와의 호환성을 위해 일부 라이브러리는 ctx.React, ctx.ReactDOM, ctx.antd, ctx.dayjs와 같이 최상위 레벨에도 노출되어 있습니다. 유지보수 및 문서 검색의 편의를 위해 ctx.libs.xxx 형식을 통일해서 사용하는 것을 권장합니다.

#지연 로딩 (Lazy Loading)

lodash, formula, math 등은 지연 로딩 방식을 사용합니다. ctx.libs.lodash에 처음 접근할 때 동적 import가 발생하며, 이후에는 캐시된 인스턴스를 재사용합니다. React, antd, dayjs, antdIcons는 컨텍스트에 미리 설정되어 있어 즉시 사용할 수 있습니다.

#예시

#React와 Ant Design 렌더링

const { Button, Card } = ctx.libs.antd;

ctx.render(
  <Card title="제목">
    <Button type="primary">클릭</Button>
  </Card>
);

#Hooks 사용

const { React } = ctx.libs;
const { useState } = React;
const { Button } = ctx.libs.antd;

const App = () => {
  const [count, setCount] = useState(0);
  return <Button onClick={() => setCount((c) => c + 1)}>{count}</Button>;
};
ctx.render(<App />);

#아이콘 사용

const { Button } = ctx.libs.antd;
const { UserOutlined, HeartOutlined } = ctx.libs.antdIcons;

ctx.render(<Button icon={<UserOutlined />}>사용자</Button>);

#dayjs 날짜 처리

const now = ctx.libs.dayjs();
const formatted = now.format('YYYY-MM-DD HH:mm:ss');
ctx.message.info(formatted);

#lodash 유틸리티 함수

const user = { profile: { name: 'Alice' } };
const name = ctx.libs.lodash.get(user, 'profile.name', 'Unknown');

#formula 공식 계산

const values = [1, 2, 3, 4];
const sum = ctx.libs.formula.SUM(values);
const avg = ctx.libs.formula.AVERAGE(values);

#math 수학 표현식

const result = ctx.libs.math.evaluate('2 + 3 * 4');
// result === 14

#주의사항

• ctx.importAsync와 혼용 시: ctx.importAsync('react@19')를 통해 외부 React를 로드한 경우, JSX는 해당 인스턴스를 사용합니다. 이때 ctx.libs.antd와 혼용하지 마십시오. antd는 해당 React 버전과 호환되는 버전을 함께 로드해야 합니다 (예: ctx.importAsync('antd@5.x'), ctx.importAsync('@ant-design/icons@5.x')).
• 다중 React 인스턴스: "Invalid hook call"이 발생하거나 hook dispatcher가 null인 경우, 대개 여러 개의 React 인스턴스가 존재하기 때문입니다. ctx.libs.React를 읽거나 Hooks를 호출하기 전에 await ctx.importAsync('react@버전')을 먼저 실행하여 페이지와 동일한 React 인스턴스를 공유하도록 하십시오.

#관련 문서

• ctx.importAsync() - 외부 ESM 모듈(특정 버전의 React, Vue 등)을 필요에 따라 로드
• ctx.render() - 컨테이너에 콘텐츠 렌더링