@haxtheweb/create
Version:
CLI for all things HAX the web
269 lines (231 loc) • 14.8 kB
Markdown
[](https://www.repostatus.org/#active)
[](https://securityscorecards.dev/viewer/?uri=github.com/haxtheweb/create)
[](/SUPPORT.md)
[](https://opensource.org/licenses/Apache-2.0)
[](/CODE_OF_CONDUCT.md)
[](https://discord.gg/EKYJAjqGhf)
[](https://lit.dev/)
[](https://haxtheweb.org/)
[](https://www.npmjs.com/package/@haxtheweb/create)
[](https://github.com/haxtheweb/create/actions)
[](https://twitter.com/intent/follow?screen_name=haxtheweb)
# HAX The CLI
Rapidly build web components for the Web that work with HAX. HAX The Web's CLI tools empower you to rapidly..
```bash
# this allows you to then use hax command
npm install @haxtheweb/create --global
# then run this for interactive prompt
hax start
```
# Commands
## Default / global / new context
- `hax start` - fun ascii art and interactive CLI (via [clack](https://www.clack.cc/) )
- `hax webcomponent my-element --y` - Make a new HAX capable, i18n wired, Design system (DDD) driven web component
- if in a monorepo root, will place in correct location / inherit settings
- `hax site mysite --y` - create a new HAXsite (HAXcms, single site)
- `hax site mysite --skeleton-machine-name clean-one --y` - create a new HAXsite from an installed skeleton template
- `hax audit` - Audits web components for compliance with DDD (HAX design system)
- `hax update` - HAX CLI self update
- `hax party` - Display options to join the HAX community and get involved!
- `hax skills list` - List bundled agent skills shipped with the CLI
- `hax skills install --all` - Install all bundled skills into `~/.agents/skills/` for any agent to use
- `hax skills install <name>` - Install a specific bundled skill
## Bundled Agent Skills
This CLI ships interface skills in `src/skills/` (compiled to `dist/skills/`) that teach agents how to use the `hax` CLI. These are version-locked to the CLI — when a command or flag ships, the matching skill updates in the same release.
**Bundled skills**:
- `hax-site-building` — HAXcms site creation, JOS, site.json, page management
- `hax-claudehax` — ClaudeHAX plugin, `/hax` slash command, CLI operation
- `hax-webcomponent-dev` — `hax webcomponent`, HAXSchema, component scaffolding
- `hax-ecosystem-onboarding` — environment setup, first scaffold, repo cloning
Install them for your agents:
```bash
hax skills install --all # all interface skills → ~/.agents/skills/
hax skills install hax-site-building # specific skill
hax skills install --all --path ./test-site/.agents/skills # custom target
```
Workflow and knowledge skills (media ingestion, OpenStax conversion, DDD design system, issue analysis, rule management, Bloom's taxonomy) live in the [PRAW repository](https://github.com/haxtheweb/praw) and are not bundled with the CLI.
## --help
Run `hax help` or `hax webcomponent --help` or `hax site --help` for up-to-date listing
```
Usage: hax [options] [command]
Options:
--
--v Verbose output
--debug Output for developers
--format <char> Output format; json (default), yaml
--path <char> where to perform operation
--name <char> name of the project/web component
--npm-client <char> npm client to use (must be installed)
npm, yarn, pnpm (default: "npm")
--y yes to all questions
--skip skip frills like animations
--quiet remove console logging
--auto yes to all questions, alias of y
--no-i prevent interactions / sub-process, good
for scripting
--to-file <char> redirect command output to a file
--no-extras skip all extra / automatic command
processing
--root <char> root location to execute the command from
--org <char> organization for package.json
--author <char> author for site / package.json
--writeHaxProperties Write haxProperties for the element
--import-site <char> URL of site to import
--import-structure <char> import method to use:
pressbooksToSite
elmslnToSite
haxcmsToSite
notionToSite
gitbookToSite
evolutionToSite
ploneToSite
wordpressPagesToSite
drupalBookToSite
htmlToSite
docxToSite
--node-op <char> node operation to perform
--item-id <char> node ID to operate on
--domain <char> published domain name
--title-scrape <char> CSS Selector for `title` in resource
--content-scrape <char> CSS Selector for `body` in resource
--items-import <char> import items from a file / site
--recipe <char> path to recipe file
--custom-theme-name <char> custom theme name
--custom-theme-template <char> custom theme template; (options: base,
polaris-flex, polaris-sidebar)
--skeleton-file <char> path to skeleton JSON file
--skeleton-machine-name <char> skeleton machine name (installed template)
to create a site from
--source <char> rsync source directory or remote path
--destination <char> rsync destination directory or remote path
--exclude <char> comma-separated patterns to exclude from
rsync
--dry-run perform rsync dry run
--delete delete extraneous files from destination
--repos <char...> repositories to clone
-V, --version output the version number
--title <char> Title
--content <char> Page content
--slug <char> Path (slug)
--published <char> Publishing status
--tags <char> Tags
--parent <char> Parent
--order <char> Order
--theme <char> Theme
--hide-in-menu <char> Hide in menu
-h, --help display help for command
Commands:
start Select which hax sub-program to run
update [options] hax cli self update
serve Launch HAXsite in development mode
(http://localhost)
site [options] [action] create or administer a HAXsite
wc|webcomponent [options] [action] Create Lit based web components, with HAX
recommendations
audit [options] Audits web components for compliance with
DDD (HAX design system)
party [options] [action] Party time! Join the HAX community and
get involved!
help [command] display help for command
```
## Examples
For a detailed list of example commands that you can perform with `hax` see [examples](examples.md).
## Manual
### Linux / macOS
Run `man hax` to get detailed manual.
# Alternative Usage
```bash
# also this will invoke 1x
npx @haxtheweb/create
# this is same as above, better windows CLI support
npm init @haxtheweb
```
```bash
# script creating a new element called my-element w/ all defaults
npm run hax -- --name my-element --y
```
## Windows problems?
Try setting a different cache path to load from `npm config set cache C:\tmp\nodejs\npm-cache --global`
If you wish to use PowerShell over Command Prompt, you may need to change your execution policy to allow scripts using the `Set-ExecutionPolicy` command with the `-ExecutionPolicy` and `-Scope` parameters. You should **not** need to do this if you are using Command Prompt.
```powershell
# To see your current execution policy
Get-ExecutionPolicy
```
`Set-ExecutionPolicy` command documentation: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.4
Follow the prompts and let's HAX the Web together!
## Web component
Step through answering basic install questions to build a HAX capable web component that works anywhere! Features:
- LitElement based
- DDDSuper class which adds our design system in
- Common conventions used to demonstrate and work with property binding
- Minor CSS variable inclusion for initial learning
## HAX Site
Build a HAX site that can be published and transported anywhere. Your users might love it on the front end, now you get the simplicity of building on the CLI.
- Same HAX sites you can create via front end
- Templated files that work just like any HAX site
- End points baked in to do CLI commands for common endpoint operations like adding pages, deleting and editing.
- Ability to import via URL just like the front-end
- Ability to export a site as a skeleton JSON template and install skeletons for reuse
- Ability to create a new site from a local skeleton file or installed skeleton machine name
- Theme development starting point to be able to build themes locally
- Primed to publish to gh-pages, vercel and more
## HAX Audit
Audits your HAX based web components to suggest improvements to better align with DDD, the design system built into HAX components.
- Use `.dddignore` file to instruct audit program what files should be ignored. Each component generated comes with a `.dddignore` file in its root directory.
- Run command from root of the component project.
- Provides suggested changes for component CSS to align with DDD design standards, if a change cannot be suggested, developer will be refered to look at the manual for a change that works for them!
### `.dddignore` Template
```gitignore
# Directories
# (Must start with with / or \, as seen below)
/.github # Inline comments are supported
/.vscode
/.idea
/locales
\test
/dist
/build
/public # ignored by program regardless of presence in .dddignore
/node_modules # ignored by program regardless of presence in .dddignore
# Files
# (Must include filename and extension, as seen below)
LICENSE
.dddignore
.editorconfig
.gitignore
.nojekyll
.npmignore
.surgeignore
rollup.config.js
# File extension
# (Must start with *, as seen below)
*.md
*.yml
*.json
*.toml
*.mjs
*.cjs
*.png
*.ico
*.svg
*.jpg
*.jpeg
```
# Get Help / Issues / Support
- Discord Channel - https://discord.gg/EKYJAjqGhf
- Unified issue queue - https://github.com/haxtheweb/issues/issues
- DDD Documentation - https://haxtheweb.org/documentation/ddd
- Using Merlin directly in any HAX spaces and type "Issue" to jump start a report!
## Watch and Learn more about HAX here:
- Try Hax: https://hax.cloud
- HAXCellence https://haxtheweb.org/what-is-hax
- Youtube channel - https://www.youtube.com/@haxtheweb
# Related links and tech
- [NPM Package list](https://www.npmjs.com/org/haxtheweb)
- [HAXcms (NodeJS)](https://github.com/haxtheweb/haxcms-nodejs)
- [HAXcms (PHP)](https://github.com/haxtheweb/haxcms-php)
- [Storybook docs](https://open-apis.hax.cloud/)
- [HAX [dot] PSU](https://hax.psu.edu)
- [HAX doc site](https://haxtheweb.org/)
- [HAX + 11ty](https://github.com/haxtheweb/hax11ty)
