RedwoodJS 快速上手使用 Create Redwood App 从零初始化全栈应用【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwoodRedwoodJS 是一个面向全栈 Web 应用的全功能框架而create-redwood-app正是你开启 Redwood 之旅的官方脚手架工具。本文以 Redwood v6 版本文档为主体结合当前仓库中 create-redwood-app 的源码实现完整讲解如何使用该工具初始化项目、交互式问答中每个选项的含义与取舍、可用的命令行 Flags 及其别名、以及启动开发服务器后的访问端口与调试入口帮助你一条命令搭建起可运行的 Redwood 全栈工程。一、快速开始一条命令创建 Redwood 应用要创建一个全新的 Redwood 项目只需在终端中执行yarn create redwood-app your-app-name其中your-app-name是你希望创建的项目目录名。该命令会通过 npm/yarn 拉取 create-redwood-app 脚手架包将仓库 templates 目录下的ts/js两套模板中的项目骨架复制到目标目录随后进入交互式问答流程。该命令最终执行的入口为 create-redwood-app.js它在包发布时由 build.ts 使用 esbuild 打包为dist/create-redwood-app.js并在 package.json 中通过bin字段暴露为命令行工具。如果你想跳过交互直接创建也可以带参数运行例如yarn create redwood-app my-redwood-app --typescript --git-init --commit-message Initial commit --yarn-install支持.作为目标目录从源码看handleTargetDirPreference 支持将目标目录指定为.即在当前目录中创建项目。如果不传目录参数CLI 会交互式地询问 Where would you like to create your Redwood app?默认值为my-redwood-app。源码还特意拦截了~username形式的目录语法返回错误并提示使用完整路径或命令行参数并借助untildify展开~/开头的路径。二、创建前的环境准备Set up for successNode.js 版本要求Redwood v6 要求 Node.js 版本18.0.0 或更高如果你的 Node 版本是19.0.0 或更高仍然可以使用 Create Redwood App但需要注意这可能会使你的项目与某些部署目标如 AWS Lambda不兼容。原因是更新版本的 Node 运行时会改变部分 API 行为而 serverless 平台的运行时版本通常是固定的。查看当前 Node 版本node -v如果需要升级 Node或在多个版本之间切换官方推荐使用nvmNode Version Manager具体配置可参考仓库中的 使用 nvm 指南。源码层面的版本校验脚手架在创建项目前会执行executeCompatibilityCheck见 create-redwood-app.js它读取模板根目录package.json中声明的engines字段当前模板为node: 20.x见 ts 模板 package.json调用check-node-version检查实际 Node 与 Yarn 版本是否满足要求。版本不满足时CLI 会区分两种情况处理Node 版本过低semver.lt判定小于所需最低版本会直接终止安装并提示升级Node 版本过高超出预期范围则显示警告提示这可能使你的项目与部分部署目标尤其是使用 AWS Lambda 的目标不兼容并让你选择忽略错误继续安装还是退出安装。Yarn 版本要求Redwood 还需要Yarn 1.22.21 或更高版本yarn -v升级 Yarn 的方法可参考 Yarn 官方文档https://yarnpkg.com/getting-started/install。源码中通过isYarnBerryOrNewer见 create-redwood-app.js解析npm_config_user_agent环境变量来判断你使用的是 Yarn 1 还是 Yarn 2Berry这一判断直接决定了后续是否运行yarn install的提问是否出现以及--yarn-install标志是否可用。其他可选替代方案源码中USE_GITPOD_TEXT还内置了一个替代方案提示如果本地环境长期无法满足 Node/Yarn 版本要求也可以使用GitPod在线 IDE 直接启动 Redwood 示例项目无需在本地安装任何运行时。三、交互式问答创建过程中的三个选择运行yarn create redwood-app your-app-name后脚手架会依次弹出以下问题每个问题在源码中都有对应的处理函数见 create-redwood-app.js。1. Select your preferred language选择语言选项TypeScript默认或 JavaScript说明选择 TypeScript 会从 templates/ts 模板生成项目含tsconfig.json、.ts/.tsx文件选择 JavaScript 则从 templates/js 模板生成含jsconfig.json、.js/.jsx文件。两套模板的结构完全一致均包含api/后端Prisma schema、GraphQL 函数、directives、lib 等与web/前端React 入口、Routes、Pages、Layouts、Components 等两大目录。后续迁移即使一开始选择了 JavaScript之后也可以随时将 JavaScript 项目转换为 TypeScript先运行yarn rw setup tsconfig为 web/api 两侧添加tsconfig.json同时可删除两侧的jsconfig.json然后按.js → .ts、.jsx → .tsx的方式渐进式重命名文件即可。2. Do you want to initialize a git repo?是否初始化 git 仓库选项yes默认或 no说明选择 yes 后会继续要求你Enter a commit message输入提交信息默认提交信息为Initial commit。事后补救如果当时选择 no也可以之后手动初始化并提交cd your-app-name git init git add . git commit -m Initial commit源码佐证当选择初始化 git 时initializeGit 会在新项目目录内执行git init git add . git commit -m commitMessage而提交信息的默认值由常量INITIAL_COMMIT_MESSAGE Initial commit定义见 create-redwood-app.js。3. Do you want to runyarn install?是否立即安装依赖选项yes默认或 no注意该提示只有在使用 Yarn 1Classic时才会出现。如果使用 Yarn 2BerryCLI 会直接跳过这一步详见下文 Flags 部分的说明。说明选择 yes 会下载并安装项目的全部依赖在源码中对应 installNodeModules在项目目录内执行yarn install。事后补救如果选择 no之后可随时执行cd your-app-name yarn install目录已存在时的处理除了上述三个问答当目标目录已存在且非空时CLI 还会弹出额外的问题见 doesDirectoryAlreadyExist给出三个选项Quit install退出安装Overwrite files in 目录 and continue install覆盖目录中的文件并继续——会先删除旧目录再重建Specify a different directory指定其他目录——重新输入一个新的目录名四、Flags一条命令跳过全部交互如果不想逐个回答交互式问题可以在命令行直接传入 Flags 来自动化创建流程。完整 Flags 列表如下Flag别名作用--yarn-install运行yarn install安装依赖--typescriptts将 TypeScript 设为首选语言传--no-typescript则使用 JavaScript--overwrite覆盖已存在的同名目录允许在非空目录中创建--git-initgit初始化 git 仓库--commit-message Initial commitm指定初始 git 提交信息--yesy自动选择所有默认选项Flags 在源码中通过yargs解析见 create-redwood-app.js。其中--overwrite与--telemetry的默认值在 yargs 中直接给出overwrite默认falsetelemetry默认true而--typescript、--git-init、--commit-message的默认值为null即未指定此时才触发交互式提问当传入--yes时typescript、git-init均回落到truecommit-message回落到默认的Initial commit。全 Flags 示例以下命令一次性启用所有选项yarn create redwood-app your-app-name --typescript --git-init --commit-message Initial commit --yarn-install关于--yarn-install的一个细节从源码看--yarn-install标志只有在 Yarn 2Berry环境下才会被注册见 create-redwood-app.js在 Yarn 1 环境下是否安装依赖由交互式问答控制。同时--yes会把 Yarn 2 下的yarn-install自动置为true。因此在 Yarn 1 下想跳过交互并自动安装依赖请使用--yes。进阶--telemetry与--no-telemetry脚手架默认开启遥测telemetry功能用于收集create命令及后续 Redwood CLI 命令的使用情况。你可以通过以下两种方式关闭在命令行传入--telemetry false或--no-telemetry设置环境变量REDWOOD_DISABLE_TELEMETRY1对应的解析逻辑位于 create-redwood-app.js。遥测实现见 telemetry.js它基于 OpenTelemetry SDK 采集系统信息OS、Shell、Node/Yarn/npm 版本、CPU 核数、内存、是否在 CI/GitPod 环境等并生成一个随机的UID写入新项目的.redwood/telemetry.txt文件见 createProjectFiles。五、安装完成后的自动流程交互式问答与文件复制完成后脚手架会根据你的选择依次执行后续步骤对应 createRedwoodApp 的主流程引擎检查executeCompatibilityCheck校验 Node/Yarn 版本是否满足模板engines要求确定目标目录handleTargetDirPreference使用命令行参数或交互输入默认my-redwood-app确定语言handleTypescriptPreferenceTypeScript默认或 JavaScript决定使用哪套模板确定 git 策略handleGitPreference/handleCommitMessagePreference是否git init并完成首次提交确定依赖安装策略handleYarnInstallPreference仅 Yarn 2 下提问或读 Flag复制模板文件createProjectFiles将模板复制到目标目录并把gitignore.template重命名为.gitignore写入遥测 UID 文件安装依赖installNodeModules可选在项目内执行yarn install生成类型generateTypes可选执行yarn rw-gen生成 GraphQL 类型与 Prisma 客户端类型初始化 gitinitializeGit可选执行git init git add . git commit -m message输出引导信息打印 Quick Start 链接并根据实际情况给出cd 项目目录、yarn install、yarn rw dev三条后续命令提示。其中**生成类型yarn rw-gen是一个容易被忽略但很重要的步骤**它负责为 GraphQL schema 与 Prisma 模型生成对应的 TypeScript 类型是后续编辑器智能提示与类型检查的基础。六、启动开发服务器项目创建完成后进入项目目录并启动开发服务器cd your-app-name yarn rw dev启动成功后你会得到以下访问地址Web 前端http://localhost:8910API 后端http://localhost:8911Redwood GraphQL Playgroundhttp://localhost:8911/graphql这些端口来自模板项目中的 redwood.toml 配置[web] title Redwood App port 8910 apiUrl /.redwood/functions [api] port 8911 [browser] open true [notifications] versionUpdates [latest]几点说明[browser] open true表示开发服务器启动时会自动在浏览器中打开http://localhost:8910你将在那里看到欢迎页Welcome Page。apiUrl默认指向/.redwood/functionsGraphQL API 会挂载在该路径下因此 Playground 地址为http://localhost:8911/graphql。关于redwood.toml的完整配置项web/api 的端口、环境变量注入、GraphQL 路径定制等可参考仓库中的 App Configuration: redwood.toml 文档。新项目里有什么模板结构速览以 TypeScript 模板templates/ts为例脚手架生成的项目包含根目录redwood.toml框架配置、graphql.config.jsGraphQL 工具配置、jest.config.js测试配置、prettier.config.js代码格式化、package.json声明redwoodjs/core依赖与node: 20.x引擎要求api/db/schema.prismaPrisma 数据模型、src/functions/graphql.tsGraphQL 服务入口、src/directives/requireAuth/skipAuth指令及其测试、src/lib/auth.ts、db.ts、logger.ts、src/services/业务服务目录web/src/App.tsx、src/Routes.tsx路由、src/pages/FatalErrorPage、NotFoundPage、src/entry.client.tsx浏览器入口、vite.config.ts等scripts/seed.ts数据库种子脚本。创建后的下一个动作项目跑起来之后官方推荐按以下节奏继续详见模板自带的 README操作数据库编辑api/db/schema.prisma定义数据模型然后运行yarn rw prisma migrate dev生成迁移再用yarn rw generate scaffold model一键生成针对该模型的完整 CRUD 页面、组件与服务前端先行使用yarn rw storybook启动 Storybook 在隔离环境中开发组件配合yarn rw generate cell name生成数据获取 Cell 的 story测试yarn rw test运行前后端 Jest 测试Redwood 为测试内置了数据库场景与 GraphQL Mock 能力部署与鉴权yarn rw setup deploy --help查看部署目标配置Netlify、Vercel、Render、AWS 等yarn rw setup auth --help配置认证内置 dbAuth 或接入第三方 Auth 提供商。七、常见问题与排查Node/Yarn 版本不满足要求CLI 会在创建前做引擎检查并给出明确的分级提示Node 过低提示你需要升级 Node 版本并建议使用 nvm 或 corepack 切换到兼容版本随后终止安装Node 过高提示你可能需要降级 Node 版本并警告可能与 AWS Lambda 等部署目标不兼容让你选择Override error and continue install忽略错误继续或Quit install退出。对应的源码逻辑见 executeCompatibilityCheck。目标目录已存在非空目录会触发三个选项退出 / 覆盖 / 指定其他目录也可以直接使用--overwrite标志跳过提问强制在已存在的同名目录中创建项目。交互被意外终止源码中每个交互提问目录、语言、git、提交信息、yarn install、目录冲突处理都包裹在 try/catch 中一旦用户取消如 CtrlCCLI 会通过遥测记录User cancelled install...事件后以非零状态码退出不会留下半成品状态。关于 Yarn 2Berry的差异使用 Yarn 2 时不会出现是否运行yarn install的提问CLI 会直接提示 Skipped yarn install step--yarn-install标志在此环境下可用依赖安装与类型生成yarn rw-gen只在选择安装时才执行。结语yarn create redwood-app是进入 RedwoodJS 世界的第一步一条命令即可获得包含apiGraphQL Prisma与webReact Vite两大侧的全栈项目骨架。通过交互式问答或 Flags 参数你可以精确控制语言TypeScript/JavaScript、git 初始化、依赖安装等初始化行为配合yarn rw dev启动开发服务器后即可在localhost:8910开发前端、在localhost:8911/graphql调试 GraphQL API。如果你想深入了解创建流程的内部实现可以直接阅读 create-redwood-app.js 与 templates 目录下的两套模板它们是理解 Redwood 项目组织方式的最佳起点。【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
