Skip to content

Commit

Permalink
docs(book): 📝 wrote cli docs
Browse files Browse the repository at this point in the history
  • Loading branch information
arctic-hen7 committed Sep 20, 2021
1 parent 0375f01 commit e321c38
Show file tree
Hide file tree
Showing 3 changed files with 67 additions and 2 deletions.
4 changes: 2 additions & 2 deletions docs/next/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@
- [Request State]()
- [Revalidation]()
- [Incremental Generation]()
- [CLI]()
- [Ejecting]()
- [CLI](./cli.md)
- [Ejecting](./ejecting.md)
- [Config Managers]()
- [Testing]()
- [Styling]()
Expand Down
35 changes: 35 additions & 0 deletions docs/next/src/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# CLI

One of the things that makes Perseus so different from most Rust frameworks is that it has its own CLI for development. The reason for this is to make using Perseus as simple as possible, and also because, if you have a look at what's in `.perseus/`, building without the CLI is really hard!

## Commands

### `build`

Builds your app, performing static generation and preparing a Wasm package in `.perseus/dist/`.

### `serve`

Builds your app in the same way as `build`, and then builds the Perseus server (which has dependencies on your code, and so needs to rebuilt on any changes just like the stuff in `.perseus/dist/`), finally serving your app at <http://localhost:8080>. You can change the default host and port this serves on with the `HOST` and `PORT` environment variables.

You can also provide `--no-build` to this command to make it skip building your app to Wasm and performing static generation. In this case, it will just build the serve rand run it (ideal for restarting the server if you've made no changes).

### `clean`

This command is the solution to just about any problem in your app that doesn't make sense, it deletes the `.perseus/` directory entirely, which should remove any corruptions! If this doesn't work, then the problem is in your code (unless you just updated to a new version and now something doesn't work, then it's probably on us, please [open an issue](https://github.com/arctic-hen7/perseus)!).

Note that this command will force Perseus to rebuild `.perseus/` the next time you run `perseus build` or `perseus serve`, which can be annoying in terms of build times. It's almost always sufficient to run this command with the `--dist` flag, which will only delete some content in `.perseus/dist/` that's likely to be problematic.

### `eject`

See the next section for the details of this command.

## Watching

Right now, the Perseus CLI doesn't support watching files for changes and rebuilding, but it soon will. Until then, you can replicate this behavior with a tool like [`entr`](https://github.com/eradman/entr) or the equivalent. Anything that watches file and reruns commands when they change will work for this.

Here's an example of watching files with `entr`:

```
find . -not -path "./.perseus/*" -not -path "./target/*" | entr -s "perseus serve"
```
30 changes: 30 additions & 0 deletions docs/next/src/ejecting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Ejecting

The Perseus CLI is fantastic at enabling rapid and efficient development, but sometimes it can be overly restrictive. If there's a use-case that the CLI doesn't seem to support, please [open an issue](https://github.com/arctic-hen7/perseus/issues/new/choose) on GitHub, and we'll look into supporting it out-of-the-box.

However, there are some things that are too advanced for the CLI to support, and, in those cases, you'll need to eject. Don't worry, you'll still be able to use the CLI itself for running your app, but you'll be given access to the engine that underlies it, and you'll be able to tweak basically anything you want.

*Note: ejecting from Perseus exposes the bones of the system, and you should be quite familiar with Rust before doing this. That said, if you're just doing it for fun, go right ahead!*

## Ejecting

`perseus eject`

This command does two things: it removes `.perseus/` from your `.gitignore` file, and it adds a new file called `.perseus/.ejected`.

After ejecting, there are a few things that change.

- You can no longer run `perseus clean` unless you provide the `--dist` flag (otherwise it would delete the engine you're tweaking!)
- A ton of files appear in Git that you should commit, all from `.perseus/`

## Architecture

Under the hood, Perseus' CLI is only responsible for running commands like `cargo run` and `wasm-pack build`. All the logic is done in `.perseus/`, which provides two crates, one for your app itself (which also contains a binary for running static generation) and another for the server that will run your app. That means that you can still use the CLI!

One of the first things you'll probably want to do if you choose to eject is to remove the `[workspace]` declaration from `.perseus/Cargo.toml` and instead add both crates inside to your project's workspace. This will make sure that linters like RLS will check your modifications to `.perseus/` for any problems, and you won't be flying blind.

The rest of the documentation on how Perseus works under the hood can be found in the *Advanced* section of the book, which you'll want to peruse if you choose to eject.

## Reversing Ejection

If, after taking a look at the innards, you decide that you'd like to find a solution for your problem that works without having to perform what can easily seem like the programming equivalent of brain surgery, you can easily reverse ejection by deleting the `.perseus/.ejected` file and running `perseus clean`, which will permanently delete your modifications and allow you to start again with a clean slate. Note that the reversal of ejection is irreversible, so it pays to have a backup of your changes in case you want to check something later!

0 comments on commit e321c38

Please sign in to comment.