@acryldev/create-blends 0.0.0-stage → 1.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +104 -2
- package/bin/create-acrylblends.js +12 -0
- package/dist/index.d.ts +94 -0
- package/dist/index.js +1069 -0
- package/dist/index.js.map +1 -0
- package/package.json +54 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 WebBoxes s.r.o.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,105 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @acryldev/create-blends
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Create an Acryl app with one command.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm create @acryldev/blends@latest my-app
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
It asks which template you want, creates `my-app`, and prints what to run next. Other package managers work the same way: `pnpm create @acryldev/blends@latest`, `yarn create acrylblends`, `bun create acrylblends@latest`.
|
|
10
|
+
|
|
11
|
+
## Templates
|
|
12
|
+
|
|
13
|
+
Every template is a Cordis app: `blend.yaml` lists the plugins that are mounted and every plugin is a folder in `plugins/`.
|
|
14
|
+
|
|
15
|
+
| Template | What you get |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| `blank` | the smallest app: the router, a server and one route, with a test |
|
|
18
|
+
| `nodejs` | a web app: routes, a server-rendered JSX page and a client component, with tests; run with Node.js 22.19 or newer |
|
|
19
|
+
| `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite through the `db` port, validated forms, search, a JSON API with a typed test client, csrf on, a test for every route |
|
|
20
|
+
| `chat` | an AI chat starter: the answer streams token by token (Server-Sent Events) from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite, tests with a mock model |
|
|
21
|
+
| `todo` | a to-do list on the router and state: CRUD routes, a page, tests |
|
|
22
|
+
| `agent` | the blank app with an offline agent that builds plugins into the running app, through the door (`acryl-app` is the old name for it and still works) |
|
|
23
|
+
|
|
24
|
+
Every template includes `AGENTS.md`, `CLAUDE.md` and a copy of the framework documentation in `docs/framework/`, so a coding agent working in the folder reads the API from the folder.
|
|
25
|
+
|
|
26
|
+
## Non-interactive use
|
|
27
|
+
|
|
28
|
+
Arguments for the initializer go after `--` with `npm create`:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
npm create @acryldev/blends@latest my-app -- --template nodejs --install --pm npm
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
| Option | |
|
|
35
|
+
| --- | --- |
|
|
36
|
+
| `--template <name>` | `blank`, `nodejs`, `notes`, `chat`, `todo` or `agent` (the same list as `acrylblends init`; `acryl-app` still means `agent`; a bare name after the directory means the same: `npm create @acryldev/blends@latest my-app notes`) |
|
|
37
|
+
| `--desktop` | put the app inside the ACRYL frame: `npm run dev` opens it with the chat, the panels and Settings. Not with a starter from a source |
|
|
38
|
+
| `--install` | install the dependencies after creating the app |
|
|
39
|
+
| `--pm <manager>` | `npm`, `pnpm`, `yarn` or `bun` (default: the one that ran the command) |
|
|
40
|
+
| `-y`, `--yes` | ask nothing: template `nodejs`, directory `acrylblends-app` unless given |
|
|
41
|
+
|
|
42
|
+
## Then
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
cd my-app
|
|
46
|
+
npm install # unless you passed --install
|
|
47
|
+
npm run dev # prints its URL; GET / answers "Acryl!"
|
|
48
|
+
npm test
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
import { Acryl } from '@acryldev/blends'
|
|
53
|
+
|
|
54
|
+
const app = new Acryl()
|
|
55
|
+
app.get('/', (c) => c.text('Acryl!'))
|
|
56
|
+
|
|
57
|
+
export default app
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Where an app's shared code comes from
|
|
61
|
+
|
|
62
|
+
An app made here holds two kinds of code that are not its own, and says so in its files:
|
|
63
|
+
|
|
64
|
+
- **The library plugins** (`plugins/door`, `@acryldev/router`, `desktop`, `instance`, `plugin-share` and the others named in
|
|
65
|
+
`plugins/library.json`) are copies of the acrylblends library, from <https://github.com/acrylblends/acrylblends>.
|
|
66
|
+
`plugins/library.lock.json` records the release each came from and a hash of every file. `npx acrylblends upgrade` brings them to the
|
|
67
|
+
newest release; when a file was changed here, it stops, shows the diff and changes nothing (`--force` replaces it and keeps a backup in
|
|
68
|
+
`.acryl/upgrade-backup/`). Fix a library plugin in acrylblends, not here; your own code goes in a plugin of your own under `plugins/`.
|
|
69
|
+
- **The frame and its parts** (`@acryldev/blends-frame`, `@acryldev/settings` and the other `@acryldev/*` packages in
|
|
70
|
+
`package.json`) and the framework (`acrylblends`) come from npm, built from the same repository (`ide/` and `packages/`). `npm install`
|
|
71
|
+
installs them; `npx acrylblends upgrade` moves `package.json` to the release it brings.
|
|
72
|
+
|
|
73
|
+
Everything else (`blend.yaml`, `src/`, your plugins under `plugins/`) is the app's own, and an upgrade never touches it.
|
|
74
|
+
|
|
75
|
+
## Links
|
|
76
|
+
|
|
77
|
+
- Documentation: https://acrylblends.github.io/docs (mirrored at https://acryl.dev/docs)
|
|
78
|
+
- The framework package: https://www.npmjs.com/package/acrylblends
|
|
79
|
+
- Source and issues: https://github.com/acrylblends/acrylblends
|
|
80
|
+
- Blends registry: https://acrylblends.github.io/blends
|
|
81
|
+
- ACRYL: https://acryl.dev
|
|
82
|
+
|
|
83
|
+
MIT license.
|
|
84
|
+
|
|
85
|
+
## The `notes` template
|
|
86
|
+
|
|
87
|
+
`npm create @acryldev/blends@latest my-notes -- --template notes` makes a small full-stack app, written to be read and copied:
|
|
88
|
+
|
|
89
|
+
- sign up and log in (scrypt password hashes from `node:crypto`, a random token in an `httpOnly` cookie, sessions in the database);
|
|
90
|
+
- notes in SQLite through the built-in `node:sqlite` (Node.js 22.19 or later, nothing native to install), with create, edit, delete and search forms, server-side validation with messages on the page, and a redirect (303) after each POST;
|
|
91
|
+
- a JSON API under `/api/notes` that shares the validation rules, with a test that uses the typed `testClient`;
|
|
92
|
+
- csrf protection on, a test for every route, and an `AGENTS.md` that describes the files so a coding agent can extend it;
|
|
93
|
+
- a live character counter and an instant filter written as a small script in the page. When the client components of `acrylblends/jsx/dom` can be served without a bundler (planned for 0.7.2), they will replace that script here.
|
|
94
|
+
|
|
95
|
+
`npx acrylblends add desktop` followed by `npm install` and `npm run desktop` runs it as a desktop window (see `docs/framework/getting-started/desktop.md`).
|
|
96
|
+
|
|
97
|
+
## Templates from a repository or a package
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
npm create @acryldev/blends@latest my-app github:owner/repo[#ref]
|
|
101
|
+
npm create @acryldev/blends@latest my-app @scope/name[@version]
|
|
102
|
+
npm create @acryldev/blends@latest my-app ./template.tgz
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The source is downloaded as a tarball (never cloned) or packed with `npm pack --ignore-scripts`, unpacked, and read: it must hold an `acryl.template.json` (`name`, `description`, optional `plugins`), it is checked for secrets, and only then is the folder created. Nothing of the template is installed or run; if its `package.json` defines install scripts they are listed, and `--install` prints what will run before it runs. See the create-acrylblends guide in `docs/framework/guides/`.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// A Node too old to run the package is told so in plain words, before anything is loaded that would fail on it.
|
|
3
|
+
const [major, minor] = process.versions.node.split('.').map(Number)
|
|
4
|
+
if (major < 22 || (major === 22 && minor < 19)) {
|
|
5
|
+
console.error(
|
|
6
|
+
`Node 22.19+ needed, you have ${process.versions.node}: install it from https://nodejs.org or with nvm (nvm install 22).`,
|
|
7
|
+
)
|
|
8
|
+
process.exit(1)
|
|
9
|
+
}
|
|
10
|
+
const { runCreate } = await import('../dist/index.js')
|
|
11
|
+
|
|
12
|
+
process.exitCode = await runCreate(process.argv.slice(2))
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one place this package names the framework. The templates are written with `__PACKAGE__` and `__RANGE__` (the range is stamped at create time from the framework version this package carries, see `frameworkRange`), and the text of `AGENTS.md` with
|
|
3
|
+
* `__PACKAGE__`, so a rename (for example to `acryl`) is a change here and in `scripts/lib/names.mjs`, which a test keeps equal.
|
|
4
|
+
*/
|
|
5
|
+
export declare const PACKAGE = "@acryldev/blends";
|
|
6
|
+
export declare const CLASS = "Acryl";
|
|
7
|
+
export declare const CREATE = "@acryldev/create-blends";
|
|
8
|
+
/** The file that makes a folder a template other people can create apps from (`${CREATE} <name> github:owner/repo`). */
|
|
9
|
+
export declare const TEMPLATE_MANIFEST = "acryl.template.json";
|
|
10
|
+
/** How the bytes of a source are obtained; real by default, replaced in tests. */
|
|
11
|
+
interface Fetchers {
|
|
12
|
+
/** The body at a URL (a GitHub tarball); `headers` carry the person's GitHub token for a private repository. */
|
|
13
|
+
download(url: string, headers?: Readonly<Record<string, string>>): Promise<Uint8Array>;
|
|
14
|
+
/** The person's GitHub token (GITHUB_TOKEN, GH_TOKEN, else `gh auth token`), asked for only when a repository is not public. */
|
|
15
|
+
githubToken?(): string | undefined;
|
|
16
|
+
/** `npm pack <spec> --ignore-scripts` into `dest`; the path of the tarball. */
|
|
17
|
+
pack(spec: string, dest: string): string;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* The templates: the same list as acrylblends init (the framework package makes every one of them; @acryldev/create-blends delegates). A test compares this list and its summaries with the
|
|
21
|
+
* framework package's, so they cannot drift.
|
|
22
|
+
*/
|
|
23
|
+
export declare const TEMPLATES: readonly ["blank", "nodejs", "notes", "chat", "todo", "agent"];
|
|
24
|
+
export type Template = (typeof TEMPLATES)[number];
|
|
25
|
+
export declare const TEMPLATE_SUMMARY: Record<Template, string>;
|
|
26
|
+
/** Names that were templates once and still work. */
|
|
27
|
+
export declare const TEMPLATE_ALIASES: Record<string, Template>;
|
|
28
|
+
export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
|
|
29
|
+
export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
|
|
30
|
+
/** The version of this package. */
|
|
31
|
+
export declare const VERSION: string;
|
|
32
|
+
export declare const HELP: string;
|
|
33
|
+
/** A command line mistake. The command prints it with the help text and exits 2. */
|
|
34
|
+
export declare class UsageError extends Error {
|
|
35
|
+
name: string;
|
|
36
|
+
}
|
|
37
|
+
export interface Io {
|
|
38
|
+
stdout: {
|
|
39
|
+
write(text: string): unknown;
|
|
40
|
+
};
|
|
41
|
+
stderr: {
|
|
42
|
+
write(text: string): unknown;
|
|
43
|
+
};
|
|
44
|
+
cwd: string;
|
|
45
|
+
env: Record<string, string | undefined>;
|
|
46
|
+
/** Ask one question; `undefined` when there is no terminal to ask on. */
|
|
47
|
+
ask: ((question: string) => Promise<string>) | undefined;
|
|
48
|
+
/** Run a program, showing its output; resolves to the exit code. */
|
|
49
|
+
run(command: string, args: string[], cwd: string): Promise<number>;
|
|
50
|
+
/** How a template source is fetched; the real network and npm by default. */
|
|
51
|
+
fetchers?: Fetchers;
|
|
52
|
+
}
|
|
53
|
+
export declare function processIo(): Io;
|
|
54
|
+
export interface CreateOptions {
|
|
55
|
+
directory: string | undefined;
|
|
56
|
+
template: Template | undefined;
|
|
57
|
+
install: boolean;
|
|
58
|
+
/**
|
|
59
|
+
* Put the app inside the ACRYL frame, as `acrylblends init --desktop` does. On for a template and a registry blueprint, on for another source only with
|
|
60
|
+
* `--desktop`, off with `--bare`.
|
|
61
|
+
*/
|
|
62
|
+
desktop: boolean;
|
|
63
|
+
/** Start the app when it is created and installed (`<pm> run dev`), only when there is a terminal to show it in. Off with `--no-start`. */
|
|
64
|
+
start: boolean;
|
|
65
|
+
pm: PackageManager | undefined;
|
|
66
|
+
yes: boolean;
|
|
67
|
+
/** `github:owner/repo[#ref]`, `@scope/name`, a packed `.tgz`, a folder, or a registry id: a template from outside this package. */
|
|
68
|
+
source: string | undefined;
|
|
69
|
+
/** Where registry ids are read from; the public registry by default. */
|
|
70
|
+
registry: string | undefined;
|
|
71
|
+
}
|
|
72
|
+
export declare function isTemplate(value: string): value is Template;
|
|
73
|
+
/** The template a name means: itself, or what an old name stands for. */
|
|
74
|
+
export declare function resolveTemplate(value: string): Template | undefined;
|
|
75
|
+
export declare function parseCreateOptions(argv: readonly string[]): CreateOptions;
|
|
76
|
+
/** A valid package name from a directory name: lower case letters, digits and dashes. */
|
|
77
|
+
export declare function nameFrom(directory: string): string;
|
|
78
|
+
/**
|
|
79
|
+
* The range a created app asks for: the framework version this package was released with, so a new app depends on the release that made it (and gets what that release's
|
|
80
|
+
* commands can do), never an older one. A caret range, so it also takes the newer patch releases.
|
|
81
|
+
*/
|
|
82
|
+
export declare function frameworkRange(): string;
|
|
83
|
+
export declare function replacePlaceholders(text: string, name: string): string;
|
|
84
|
+
/**
|
|
85
|
+
* A new app is a git repository from the start, as `acrylblends init` makes it: the frame's versions, Files and Changes work on it, and its first
|
|
86
|
+
* version is the app as created. A folder that already is a repository, or a machine without git, is left alone.
|
|
87
|
+
*/
|
|
88
|
+
export declare function startRepository(directory: string): void;
|
|
89
|
+
/** An app with the extensions row (what plugin-share installs through) and no plugin-share row: a starter older than sharing. */
|
|
90
|
+
export declare function lacksPluginShare(directory: string): boolean;
|
|
91
|
+
/** Create the app. Returns the exit code: 0 done, 1 refused or failed, 2 a usage error. Never calls `process.exit`. */
|
|
92
|
+
export declare function runCreate(argv: readonly string[], io?: Io): Promise<number>;
|
|
93
|
+
export {};
|
|
94
|
+
//# sourceMappingURL=index.d.ts.map
|