Books
+-
+ ${books.map(book => /* html */`
+
- + ${book.title} - ${book.price} + + + `).join('')} +
diff --git a/content/learn/articles/2024-02-11-build-your-first-h3-app.md b/content/learn/articles/2024-02-11-build-your-first-h3-app.md new file mode 100644 index 00000000..e99de3df --- /dev/null +++ b/content/learn/articles/2024-02-11-build-your-first-h3-app.md @@ -0,0 +1,325 @@ +--- +title: Build your first H3 app +description: Get started with H3 by building a simple app. +authors: + - name: Estéban S + picture: https://github.com/barbapapazes.png + twitter: soubiran_ +category: getting-started +packages: + - h3 +resources: + - label: Source Code + to: https://github.com/unjs/examples/tree/main/h3/build-your-first-app + icon: i-simple-icons-github + - label: H3 Documentation + to: https://h3.unjs.io + icon: i-heroicons-book-open + - label: H3 Examples + to: https://github.com/unjs/h3/tree/main/examples + icon: i-simple-icons-github +publishedAt: 2024-02-11 +modifiedAt: 2024-02-11 +--- + +H3 is a minimal http framework for high performance and portability. + +> [!NOTE] +> Deep dive into H3 through [the dedicated documentation](https://h3.unjs.io). + +During this tutorial, we will create a very simple app to get a wide overview of H3 capabilities. This app will serve an HTML file populated with data. There will be some forms to add and remove data. At the end, we will see how to add an API endpoint to get the data in JSON format. + +> [!TIP] +> For more complexe apps, take a look at [Nitro](https://nitro.unjs.io). + +## Prerequisites + +To follow this tutorial, we need to have [Node.js](https://nodejs.org/en/) installed on our machine with [npm](https://www.npmjs.com/). We also need to have a basic knowledge of JavaScript. + +> [!NOTE] +> Despite H3 is written in TypeScript, we don't need to know TypeScript to use it. + +## Create a New Project + +First, let's create a new npm project: + +```bash +mkdir my-h3-app +cd my-h3-app +npm init -y +``` + +Then, install H3: + +```bash +npm install h3 +``` + +And that's it! We are ready to start coding. + +## Create the App + +To create our first H3 app, we need to create an `app.mjs` file at the root of our project. Inside, we will create a new app by importing the `createApp` function from H3 and calling it: + +```js [app.mjs] +import { createApp } from 'h3' + +export const app = createApp() +``` + +:read-more{to="https://h3.unjs.io/concepts/app" title="App"} + +Do not forget the `export` keyword, it's important for the listener. + +## Add a Listener + +Speaking of listener, our app is not able to respond to any request yet. To do so, we need to add a listener. A listener is used to listen an HTTP event, transfert it to our app and send back the response. + +For our tutorial, we will use [unjs/listhen](https://listhen.unjs.io). + +In the `package.json` file, add a script named `start`: + +```json [package.json] +{ + "scripts": { + "start": "npx --yes listhen -w ./app.mjs" + } +} +``` + +This script will start a server listening on port `3000` using our app and watching for changes. + +We can now run the command `npm start` to start our server. + +## Create a Router + +Now that our app is ready to accept HTTP requests, we need to create a router to handle them. The purpose of the router is to match the request to the right handler. + +With H3, we've just to use the function `createRouter` and add it to our app: + +```js [app.mjs] +import { createApp, createRouter } from 'h3' + +export const app = createApp() + +const router = createRouter() + +app.use(router) +``` + +The `app.use(router)`{lang="js"} is necessary to add the router to our app. + +:read-more{to="https://h3.unjs.io/concepts/router" title="Router"} + +## Add our First Handler + +We have an app and a router. The only thing missing is the handlers. A handler is a function that will be called when a request matches the route. + +> [!NOTE] +> We may refer to controllers in other frameworks. + +To add a handler, we can use any of the HTTP methods available on the router. For our tutorial, we will use the `get` method to handle the `GET` requests. + +```js [app.mjs] +// ... + +const router = createRouter() + +router.get('/', () => { + return 'Hello World!' +}) + +// ... +``` + +In the code above, we added a handler for the `/` route. This handler will send the string `Hello World!` to the client with a simple `return`{lang="js"}. + +:read-more{to="https://h3.unjs.io/concepts/event-handlers" title="Event Handlers"} + +## Our First HTML Page + +For this first route, we will get the books from a static array and render them in an HTML page. For each book, we will add a for to remove it from the database. Under the list, we will add a form to add a new book. + +For the style, we will use [Pico CSS](https://picocss.com/). + +```js [app.mjs] +// ... + +const router = createRouter() + +const books = [ + { title: 'The Hobbit', price: 10 }, + { title: 'The Lord of the Rings', price: 20 }, +] + +router.get('/', defineEventHandler(() => { + return /* html */` + +
+