Skip to content

Commit 3b11312

Browse files
committed
feat: 更新文档以推荐使用生成器创建新项目,并添加模板选择功能
1 parent b859f4e commit 3b11312

File tree

8 files changed

+130
-28
lines changed

8 files changed

+130
-28
lines changed

README.md

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,20 @@ ObjectQL is organized as a Monorepo to ensure modularity and universal compatibi
4545

4646
## ⚡ Quick Start
4747

48-
### 1. Installation
48+
### 0. Use the Generator (Recommended)
49+
50+
The fastest way to start is using the CLI to scaffold a new project.
51+
52+
```bash
53+
# Create a new project
54+
npm create @objectql@latest my-app
55+
56+
# Choose a template when prompted (hello-world or starter)
57+
```
58+
59+
### 1. Manual Installation
60+
61+
If you prefer to install manually:
4962

5063
```bash
5164
# Install core and a driver (e.g., Postgres or SQLite)

docs/guide/cli.md

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,26 +16,30 @@ You can then run it via `npx objectql` or add scripts to your `package.json`.
1616

1717
### 2.1 `init` (Create Project)
1818

19-
Create a new ObjectQL project from a starter template.
19+
The recommended way to create a new ObjectQL project is using the initialization package.
2020

2121
```bash
22-
npx objectql init [options]
22+
npm create @objectql@latest [name] [options]
2323
```
2424

2525
**Options:**
2626

2727
| Option | Alias | Default | Description |
2828
| :--- | :--- | :--- | :--- |
2929
| `--template <template>` | `-t` | `starter` | Template to use (`starter`, `hello-world`). |
30-
| `--name <name>` | `-n` | - | Project name. |
31-
| `--dir <path>` | `-d` | - | Target directory. |
3230
| `--skip-install` | | `false` | Skip dependency installation. |
3331
| `--skip-git` | | `false` | Skip git initialization. |
3432

3533
**Example:**
3634

3735
```bash
38-
npx objectql init -t starter -n my-app
36+
npm create @objectql@latest my-app -- --template showcase
37+
```
38+
39+
Alternatively, if you already have the CLI installed globally or in a project, you can use the legacy `init` command:
40+
41+
```bash
42+
npx objectql init [options]
3943
```
4044

4145
### 2.2 `generate` (Type Generation)

docs/guide/getting-started.md

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,29 +12,26 @@
1212

1313
The fastest way to get started is using the CLI to scaffold a project.
1414

15-
### 1. Minimal Setup (Hello World)
15+
### 1. Create a New Project
1616

17-
Create a single-file project to learn the basics.
17+
The easiest way to start is using the generator.
1818

1919
```bash
20-
# Initialize a new project
21-
npx @objectql/cli init --template hello-world --name my-first-app
20+
# Standard Setup (Recommended) - Full Project Tracker Demo
21+
npm create @objectql@latest my-app -- --template starter
2222

23-
# Enter directory
24-
cd my-first-app
25-
26-
# Start the app
27-
npm start
23+
# Minimal Setup - Single File
24+
npm create @objectql@latest my-app -- --template hello-world
2825
```
2926

30-
This will create an `index.ts` file that defines a schema, initializes an in-memory SQLite database, and runs some queries.
27+
This will create a new project with all necessary dependencies.
3128

3229
### 2. Standard Setup (Project Tracker)
3330

34-
For building real applications, use the `starter` template. This sets up a proper folder structure with YAML metadata, TypeScript logic hooks, and relationship management.
31+
For building real applications, use the `showcase` template. This sets up a proper folder structure with YAML metadata, TypeScript logic hooks, and relationship management.
3532

3633
```bash
37-
npx @objectql/cli init --template starter --name project-tracker
34+
npm create @objectql@latest project-tracker -- --template showcase
3835
```
3936

4037
This structure follows our **Best Practices**:

packages/tools/cli/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
},
2727
"scripts": {
2828
"build": "tsc && pnpm run copy-templates",
29-
"copy-templates": "rm -rf templates && mkdir -p templates && cp -r ../../../examples/quickstart/hello-world templates/ && cp -r ../../../examples/showcase/project-tracker templates/ && rm -rf templates/*/node_modules templates/*/dist",
29+
"copy-templates": "rm -rf templates && mkdir -p templates && cp -r ../../../examples/quickstart/hello-world templates/ && cp -r ../../../examples/showcase/project-tracker templates/starter && rm -rf templates/*/node_modules templates/*/dist",
3030
"watch": "tsc -w",
3131
"test": "jest"
3232
},

packages/tools/create/README.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# @objectql/create
2+
3+
The easiest way to get started with ObjectQL.
4+
5+
## Usage
6+
7+
```bash
8+
npm create @objectql@latest
9+
```
10+
11+
Follow the prompts to create your new ObjectQL application.
12+
13+
## Arguments
14+
15+
You can also pass arguments directly:
16+
17+
```bash
18+
npm create @objectql@latest <project-name> --template <template-name>
19+
```
20+
21+
- `<project-name>`: Name of the project directory.
22+
- `--template`: Template to use (e.g. `hello-world` or `showcase`).
23+
24+
## Features
25+
26+
- **Embedded Templates**: No internet connection required to fetch templates.
27+
- **Auto-Cleanup**: Automatically cleans up `package.json` configurations (strips `private: true`, resolves workspace versions).
28+
- **Interactive**: Uses `enquirer` for a smooth interactive experience if no arguments are provided.

packages/tools/create/package.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@
1010
"templates"
1111
],
1212
"scripts": {
13-
"build": "tsc && pnpm run copy-templates",
14-
"copy-templates": "rm -rf templates && mkdir -p templates && cp -r ../../../examples/quickstart/hello-world templates/ && cp -r ../../../examples/showcase/project-tracker templates/ && rm -rf templates/*/node_modules templates/*/dist"
13+
"build": "tsc && node scripts/copy-templates.js",
14+
"copy-templates": "node scripts/copy-templates.js"
1515
},
1616
"dependencies": {
1717
"chalk": "^4.1.2",
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
const fs = require('fs-extra');
2+
const path = require('path');
3+
4+
async function copyTemplates() {
5+
const root = path.resolve(__dirname, '..');
6+
const templatesDir = path.join(root, 'templates');
7+
const examplesDir = path.resolve(root, '../../../examples');
8+
9+
// Clean
10+
await fs.remove(templatesDir);
11+
await fs.ensureDir(templatesDir);
12+
13+
const filterFunc = (src, dest) => {
14+
const stats = fs.statSync(src);
15+
const filename = path.basename(src);
16+
17+
// Directory exclusions
18+
if (stats.isDirectory()) {
19+
return !['node_modules', 'dist', '.turbo', '.git'].includes(filename);
20+
}
21+
// File exclusions
22+
return !['.DS_Store', 'pnpm-lock.yaml', 'yarn.lock', 'package-lock.json'].includes(filename);
23+
};
24+
25+
const tasks = [
26+
{
27+
src: path.join(examplesDir, 'quickstart/hello-world'),
28+
dest: path.join(templatesDir, 'hello-world')
29+
},
30+
{
31+
src: path.join(examplesDir, 'showcase/project-tracker'),
32+
dest: path.join(templatesDir, 'starter')
33+
}
34+
];
35+
36+
for (const task of tasks) {
37+
if (!fs.existsSync(task.src)) {
38+
console.warn(`Warning: Source not found: ${task.src}`);
39+
continue;
40+
}
41+
console.log(`Copying ${task.src} -> ${task.dest}`);
42+
await fs.copy(task.src, task.dest, { filter: filterFunc });
43+
}
44+
45+
console.log('Templates copied successfully.');
46+
}
47+
48+
copyTemplates().catch(err => {
49+
console.error(err);
50+
process.exit(1);
51+
});

packages/tools/create/src/bin.ts

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ program
1313
.name('create-objectql')
1414
.description('Scaffold a new ObjectQL project')
1515
.argument('[directory]', 'Directory to create the project in')
16-
.option('-t, --template <name>', 'Template to use (hello-world, starter)', 'starter')
16+
.option('-t, --template <name>', 'Template to use (hello-world, starter)')
1717
.action(async (directory, options) => {
1818
console.log(chalk.bold.blue('⚡ ObjectStack AI - Project Scaffolder'));
1919

@@ -33,14 +33,23 @@ program
3333
// 2. Resolve Template Source (Embedded)
3434
// The templates are located in ../templates relative to the dist/bin.js file
3535
// dist/bin.js -> ../templates -> package-root/templates
36-
// Map 'project-tracker' to 'starter' if needed, or rely on correct copying
3736
let templateName = options.template;
38-
if (templateName === 'basic') templateName = 'starter';
39-
// If user says "starter", we expect "project-tracker" to be copied to "starter" folder, OR we adjust here.
40-
// Let's assume we copy "project-tracker" to "starter" in build script.
37+
38+
if (!templateName) {
39+
const response = await prompt<{ template: string }>({
40+
type: 'select',
41+
name: 'template',
42+
message: 'Select a starter template:',
43+
choices: [
44+
{ message: 'Standard Project (Recommended)', name: 'starter' },
45+
{ message: 'Minimal (Hello World)', name: 'hello-world' }
46+
]
47+
});
48+
templateName = response.template;
49+
}
4150

42-
// Fallback mapping if build script copies to original names
43-
if (templateName === 'starter') templateName = 'project-tracker';
51+
// Legacy mapping or aliasing if needed
52+
if (templateName === 'project-tracker') templateName = 'starter';
4453

4554
const templatePath = path.resolve(__dirname, '../templates', templateName);
4655

0 commit comments

Comments
 (0)