From 9a83331e38cbc0f9f57a7c3a4b18eea93f6e8088 Mon Sep 17 00:00:00 2001 From: Isaac Donaldson <46387819+isaacdonaldson@users.noreply.github.com> Date: Sun, 13 Oct 2024 03:35:25 -0700 Subject: [PATCH] Adding some clarifying instructions to the getting started page (#816) * add new sections for a little more explanation * add space under infobox to have proper backtick display * change '127.0.0.1' to 'localhost' --------- Co-authored-by: Elad Kaplan --- .../docs/getting-started/tour/index.md | 26 ++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docs-site/content/docs/getting-started/tour/index.md b/docs-site/content/docs/getting-started/tour/index.md index 379af1b7e..f62271178 100644 --- a/docs-site/content/docs/getting-started/tour/index.md +++ b/docs-site/content/docs/getting-started/tour/index.md @@ -49,6 +49,12 @@ If you select all defaults, you'll have: Now `cd` into your `myapp` and start your app by running `cargo loco start`: + + +
+ + If you have the `Client` asset serving option configured, make sure you build your frontend before starting the server. This can be done by changing into the frontend directory (`cd frontend`) and running `pnpm install` and `pnpm build`. +
```sh @@ -76,6 +82,7 @@ listening on port 5150
+ You don't have to run things through `cargo` but in development it's highly recommended. If you build `--release`, your binary contains everything including your code and `cargo` or Rust is not needed.
@@ -84,6 +91,11 @@ listening on port 5150 We have a base SaaS app with user authentication generated for us. Let's make it a blog backend by adding a `post` and a full CRUD API using `scaffold`: +
+ +You can choose between generating an `api`, `html` or `htmx` scaffold using the required `-k` flag. +
+ ```sh $ cargo loco generate scaffold post title:string content:text -k api @@ -127,6 +139,14 @@ listening on port 5150 ``` +
+ +Depending on which `-k` option you chose, the steps for creating a scaffolded resource will change. With the `api` flag or the `htmx` flag you can use the below example. But with the `html` flag, it is recommended you do the post creation steps in your browser. + +If you want to use `curl` to test the `html` scaffold, you will need to send your requests with the Content-Type `application/x-www-form-urlencoded` and the body as `title=Your+Title&content=Your+Content` by default. This can be changed to allow `application/json` as a `Content-Type` in the code if desired. + +
+ Next, try adding a `post` with `curl`: ```sh @@ -160,7 +180,7 @@ Your generated app contains a fully working authentication suite, based on JWTs. The `/api/auth/register` endpoint creates a new user in the database with an `email_verification_token` for account verification. A welcome email is sent to the user with a verification link. ```sh -$ curl --location '127.0.0.1:5150/api/auth/register' \ +$ curl --location 'localhost:5150/api/auth/register' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Loco user", @@ -176,7 +196,7 @@ For security reasons, if the user is already registered, no new user is created, After registering a new user, use the following request to log in: ```sh -$ curl --location '127.0.0.1:5150/api/auth/login' \ +$ curl --location 'localhost:5150/api/auth/login' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "user@loco.rs", @@ -203,7 +223,7 @@ In your client-side app, you save this JWT token and make following requests wit This endpoint is protected by auth middleware. We will use the token we got earlier to perform a request with the _bearer token_ technique (replace `TOKEN` with the JWT token you got earlier): ```sh -$ curl --location --request GET '127.0.0.1:5150/api/user/current' \ +$ curl --location --request GET 'localhost:5150/api/user/current' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' ```