快速开始

从一次类型化的本地存储读写开始。各项能力独立创建，可以按需引入现有项目。

安装

在业务项目的 .npmrc 中配置内部 npm 仓库：

@freenotes:registry=https://packages.aliyun.com/6339bf7067fa83af64bcb835/npm/freenote-npm/

pnpm add @freenotes/web-runtime

包格式与公开入口见 安装。

保存并读取偏好

在浏览器业务初始化或用户操作时执行：

import { createStorage } from '@freenotes/web-runtime';

interface Preferences {
  theme: 'light' | 'dark';
}

const storage = createStorage<Preferences>('local');
const saved = storage.set('theme', 'dark');
const theme = storage.get('theme', { fallback: 'light' });
// theme 的类型：'light' | 'dark'
// 写入成功且数据未被其它调用修改时，saved 为 true，theme 为 'dark'。

'local' 使用当前 origin 的 localStorage；需要会话存储时改为 'session'。传入 schema 后，key 和 value 都有类型检查；读取外部或历史数据时还应配置 parse 做运行时校验。

存储不可用或配额不足时，写入返回 false，读取走 fallback。重要数据应检查结果，并按需用 onError 收集诊断。读取不会自动删除无效或过期数据，完整说明见 Storage 指南。

选择下一项能力

需求	入口与指南
调用 App 能力、接收宿主通知	Bridge：createBridge()
在用户点击后复制文本	Clipboard：createClipboard()
保存结构化数据、索引查询和数据库升级	DB：createDb().open()
获取只读环境与 API 存在性快照	Environment：createEnvironment()
声明业务接口、校验响应及处理请求失败	HTTP：createHttp().createApi()
统一日志记录并接入已有上报通道	Logger：createLogger({ source, transport })
管理本地或会话 key-value 数据	Storage：createStorage()

仅 import 不读取宿主、注册监听或发起请求。factory 的配置校验、各模块的错误处理，以及数据库和订阅的释放方式，见 API 约定。

需要复制接入代码时阅读 基础示例；查询完整导出和类型时阅读 API 参考。