Install

Every story has a grand prologue, and starting a new project with Milkio is no exception.

Install

By running it and answering a few questions, you can obtain a new Milkio project.

bun create milkio

Running

Open your Milkio project directory using VS Code, or add it to your VS Code workspace.

Note

You will find a ▶️ Milkio button in the bottom left corner. Click on it and select Run Milkio & Watch to run your Milkio project.

You can also use the shortcut (⌘ + ⇧ + L) or (Alt + L) to bring up this menu.

Note that the VS Code extension will not work if you haven’t opened the directory correctly (e.g., if you opened the parent directory). If you want to open multiple projects in a single VS Code window, use the workspace feature of VS Code instead of directly opening the parent directory.

Now, Milkio is running on port 9000! You can send a POST request with your name to greet the world!

# For Linux or MacOS: You can use curl to quickly send a request
curl --request POST 'http://localhost:9000/hello-world/say' --data-raw '{"by":"milkio"}'

# For Windows: You can use Invoke-WebRequest to quickly send a request
Invoke-WebRequest -Uri "http://localhost:9000/hello-world/say" -Method Post -Body '{"by":"milkio"}'

API Testing

In the VS Code Explorer panel, open the /src/apps/hello-world/say.ts file to see its source code.

The code is divided into two parts, the action method executed when accessing the API above, and the test of the API below. You can write the logic of your API above and write the corresponding test code below.

/src/apps/hello-world/say.ts

export const test = defineApiTest(api, [
  {
    name: "Basic", // Test name
    handler: async (test) => {
      const result = await test.execute({ params: { by: "milkio" } });

      if (!result.success) return test.reject(`The result was not success`);
    },
  },
]);

Note

Once you have opened the API file containing the tests, you can run the test for this API by clicking on the flask icon in the upper right corner of VS Code. The flask icon will only appear if the API has at least one test. You can also run the tests with the shortcut (⌘ + ⇧ + R) or (Alt + R).

Client

Milkio can share types with clients and provides auto-completion and code hints. How to get started?

What’s Next?

Now that you have successfully created a Milkio project and understand the basic development pattern of Milkio, we recommend that you read the Essentials section and then explore the parts you are interested in.

If you are an experienced developer who has been using at least one other backend framework before, please read the To Forget chapter, which can help you avoid some confusion while learning Milkio.