Switching to Yao

Switching to Yao is easy. Yao focuses on generative programming. It may take time to learn a few key concepts, but once you understand them, you’ll see that Yao is a powerful tool. It helps you build applications faster and offers a great development experience.

The following sections will help you understand the core concepts of Yao and how to use them to build applications.

## Generative Programming

Before the AGI era, we believe the best way to work with AI is as a collaborator, not a master.

We aim to make generated code match hand-written code, easy to read and modify, so developers and machines can collaborate seamlessly.

- **For Human**: We want the code to be easy to read and write, clear, and intuitive.
- **For Machine**: We aim to make the code AI-friendly, easy to generate, and simple to extend.

In Yao, we use a DSL (Domain-Specific Language) to describe widgets, assemble them into applications, and use processes for atomic functions.

Yao widget could be a Table, Form, List, or Chart. It could also be a Data Model, API, Store, Flow, etc.

Yao DSL is an intermediate language understandable by both humans and machines. It can be generated by AI, created via GUI, or written manually, with seamless switching between approaches.

Use the Yao runtime to execute the code, and its built-in HTTP server to serve the application.

## Yao Application

A Yao application is a collection of widget DSLs and custom processes written in TypeScript or JavaScript.

For websites, the SUI template engine (new in version 0.10.4) can help you build the web pages you need.

Each widget type has its own directory in the project root, such as `models`, `tables`, `forms`, `apis`, `etc`.

The DSL source files are named in lowercase with the `.[TYPE].yao` extension, for example, `article.mod.yao`.

Custom process files are lowercase in the `scripts` directory, e.g., `article.ts`. The process name is `scripts.article.[FUNCTION_NAME]`.

### Directory Structure

The yao application directory structure is as follows:

```bash
app
├── aigcs # AIGC Widgets: use the prompt as a process
├── apis  # API Widgets: define the REST API
├── app.yao # Application Configuration
├── charts # Chart Widgets: chart-type pages in the admin panel
├── connectors  # AI Connectors, Database Connectors, Redis Connectors, etc.
├── dashboards  # Dashboard Widgets: dashboard-type pages in the admin panel
├── data    # The default application data directory, use the File System Process or JSAPI to access. Custom data directory can be set in environment variables.
├── db      # The sqlite database directory, the default option of database. If use another database, this directory is not necessary.
├── flows   # Flow Widgets: define the process flow
├── forms   # Form Widgets: form-type pages in the admin panel
├── icons   # The application icons used in the admin panel
├── langs   # I18n language files used in the admin panel
├── logins  # Login Widgets: login-type pages in the admin panel
├── logs    # The application log directory, the default option of log. Custom log directory can be set in environment variables.
├── models  # Model Widgets: define the data structure
├── neo     # The AI Chatbot configuration directory
├── plugins # The Default GRPC plugins directory, Custom plugins directory can be set in environment variables.
├── public  # The static files directory, can be accessed via the HTTP server. SUI template engine generates the web pages here too.
├── scripts # Custom Process: write the custom process in TypeScript or JavaScript
├── tables  # Table Widgets: table-type pages in the admin panel
└── ....    # Other widget types, or your self-defined widget types
```

### How to develop a Yao application?

There are three things you need to do to develop a Yao application:

1. **Write DSL**: Describe the widget in DSL, such as Model, API, Table, Form, etc.
2. **Write Process**: Write the custom process in TypeScript or JavaScript, or use write GRPC plugins.
3. **Debug and Run**: Use the Yao runtime to debug and run the application.

`yao start` is the command to start the application server. In **development mode**, Yao watches changes to the DSL and Process files and automatically reloads the application server.

`yao run` is the command to run a process. You can use it to test the process before integrating it into the application.

**Visual Studio Code** is the recommended IDE for developing Yao applications. set the `.yao` file type to `jsonc` in the settings, you can get the syntax highlighting and auto-completion.

For more information, see:

👉 [Building Your Application](../building-your-application)

## Tips for switching to Yao

Yao is a new way of building web applications. Here are some tips to help you switch to Yao.

**1. The Best Way to Learn: Practice and Read Source Code**

The best way to learn is through hands-on practice. Follow the documentation to build a simple application and explore the basics.

You can also read the application source code, to see how the widgets are described and how the processes are written.

Here ase some repositories you can refer to:

👉 [Yao Website Repo](https://github.com/YaoApp/website)

👉 [Yao app for Xgen developing](https://github.com/YaoApp/xgen-dev-app)

**2. Planning Before Starting Development**

In Yao, the data model is crucial. When beginning development, it's essential to plan the data structure and relationships.

When starting a new project, define the data model in the `models` directory first. Then, create the Table, Form, and API widgets based on this model.

Preparing test data and creating an import process is a good practice, as it enhances development efficiency. When deploying the application, you can use this process to import demo data.

You can generate test data using AI by sending the Model DSL to the AI and asking it to generate the data.

👉 [Import Process Example](https://github.com/YaoApp/website/blob/main/scripts/test.ts)

**3. AI Generation First, Then Manual Modification**

The fastest way to create a widget is by using AI to generate the DSL, which you can then manually tweak to fit your needs.

For example:

- Provide a Model DSL to the AI, specify your requirements, and let the AI generate a similar one. You can then adjust it as needed.
- You can also provide both a Model DSL and a Table DSL to the AI, allowing it to generate a Table widget DSL that binds to the Model. Adjust it as necessary.

The Yao Playground repository offers a simple tool for generating DSLs, which you can use. Alternatively, you can develop your own tool for this purpose.

👉 [Yao Playground](https://github.com/YaoApp/Playground)

**4. Suggestions for Frontend Developers**

Before starting development, it's helpful to have some backend knowledge:

- Understand database structures and relationships.
- Grasp the basics of REST APIs and their functionality.
- Know TypeScript or JavaScript for writing server-side custom processes.

Follow the documentation to build a simple application. Learn how to create Models, write custom processes, and develop REST APIs.

👉 [Building Your Application](../building-your-application)

👉 [Adding your component](../using-source-code/adding-your-component)

**5. Suggestions for Backend Developers**

Before starting development, some frontend knowledge is helpful:

- TypeScript or JavaScript is crucial for writing custom processes. TypeScript is recommended.
- Basic understanding of HTML, CSS, and JavaScript is essential for building websites.

Creating an admin panel in Yao is straightforward, no frontend coding required. Use Table, Form, and API widgets to build it. It's like crafting an HTML page, but more powerful, using DSL to describe the page and processes to handle data.

Follow the documentation to build a simple application and learn to use these widgets for an admin panel.

👉 [Building Your Application](../building-your-application)

👉 [Adding Your Process](../using-source-code/adding-your-process)

## Limitations of Yao

Although we have mentioned that Yao can handle everything for web development, there are still some things that may not be the best fit for Yao.

- **Highly Customized UI**: If you need a highly customized UI for an admin panel or enterprise app, you might have to write custom code. However, you can utilize Yao as a backend service. 👉 [Building your component library](../using-source-code/building-your-component-library)

- **Mobile App Client**: For a mobile app client, you may need to develop a native app or use a mobile app development framework, while using the Yao as a backend service. 👉 [REST API](../building-your-application/rest-api)

The SUI template engine, introduced in Yao 0.10.4, offers a fresh way to build web pages. It's still experimental and not fully developed, but it provides a new option for developers. For more advanced frontend needs, consider using frameworks like React or Vue and connect them to Yao via REST API. 👉 [Web Page](../building-your-application/web-page)

TypeScript is the recommended language for writing custom processes, it will be run in the V8 engine. If high-performance is nessary, add the process in Go, it's faster than TypeScript. 👉 [Adding your process](../using-source-code/adding-your-process)

## Concepts Explained

### Yao Process

A Process in Yao is an atomic function that runs in the Yao Runtime.

Yao provides hundreds of internal processes with diverse functionalities. You can also create custom processes in TypeScript or JavaScript.

- **Internal Process**: Defined in Yao's source code, you can find them in the Yao respository.
- **Custom Process**: Written in TypeScript or JavaScript, located in the `scripts` directory of your project.
- **GRPC Plugin**: Written in any language, located in the `plugins` directory of your project.

To run a process, use the `yao run` command.

For more information, see: 👉 **[Process References](../references/yao-process)**

Examples:

```bash
# Execute an internal process
yao run utils.app.Ping   # This will return the version of Yao.


# Execute a custom process defined using TypeScript
yao run scripts.test.Hello 'Yao!'   # Returns 'Hello, Yao!'

yao run scripts.test.Pets cat  # Returns a list of pets in the cat category.

```

**scripts/test.ts**

```typescript
import { Process } from "@yao/runtime";

function Hello(name: string): string {
  return `Hello, ${name}!`;
}

function Pets(category?: string): Record<string, any> {
  category = category || "dog";
  const pets = Process("models.tests.pet.Get", {
    select: ["id", "name"],
    wheres: [{ column: "category", value: category }],
  });

  return pets;
}
```

### Yao Runtime

Yao Runtime is a server-side execution environment for running processes.

- **Internal Processes** written in Go, executed directly.
- **Custom Processes** written in TypeScript or JavaScript, executed using the V8 engine. Yao provides APIs like `Process`, `File System`, and `HTTP Request` to write these processes.

**Note**: **Yao Runtime is not Node.js**. It's specifically for running processes and does not support Node.js APIs.

**Execution Methods**:

1. **CLI**: Use the `yao run` command.
2. **HTTP Server**: Use the built-in HTTP server to run processes via REST API.

### Yao Widget

A Widget in Yao is not just a traditional frontend component; it is a combination of UI, interaction, logic, and data. There are no frontend and backend concepts in a Widget; it is a self-contained unit.

A widget could be a Table, Form, List, or Chart. It could also be a Data Model, API, Store, Flow, etc.

Each Widget has a set of Processes, and some Widgets have a set of REST APIs. It can be used in other widgets, custom processes, or integrated into other applications.

A Widget is described using DSL, which is in JSON format. It can be generated by AI, created via a GUI, or written manually.

For more information, see: 👉 **[DSL References](../references/yao-dsl)**

**Model Widget**

Model Widget is used to describe the data structure, it same as the database table schema.

The Model DSL contains a set of processes to operate on the data, such as CRUD, Query, etc. You can use it directly.

```json
// Model DSL
{
  "name": "Article",
  "table": { "name": "article", "comment": "Article" },
  "columns": [
    { "name": "id", "comment": "ID", "type": "ID", "label": "ID" },
    { "label": "Title", "name": "title", "type": "string" },
    { "label": "Summary", "name": "summary", "type": "string" }
  ]
}
```

```bash
# Use the process to find the data
yao run models.article.Find 1 '::{}'
```

**Table Widget**

Table Widget is used to display the data in a admin panel. bind to the Model Widget, automatically generate the basic CRUD operations.

The Table DSL contains a set of processes and REST APIs to operate on the data, such as Find, Search etc. You can use it directly.

```json
// Table DSL
{
  "name": "Articles",
  "action": {
    "bind": { "model": "article", "option": { "form": "article" } }
  }
}
```

```bash
# Use the process to search the data
yao run yao.tables.Search article '::{}' 1 10
```

```bash
# Use the REST API to search the data
curl --request GET \
  --url https://127.0.0.1:5099/api/__yao/table/article/search \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer your_token_here'
```

## License Overview

Yao is available under two distinct licenses to accommodate various user needs: the Apache 2.0 License and the Yao Commercial License.

**Apache 2.0 License**

Under the Apache 2.0 License, you are free to use, modify, and distribute Yao. This open approach encourages integration and innovation, with the simple requirement that the original copyright notice and license terms be included in any distribution.

👉 **[Apache 2.0 License](https://github.com/YaoApp/yao/blob/main/LICENSE)**

**Yao Commercial License**

To ensure we can sustain and enhance Yao's development, we are introducing the Yao Commercial License. This license supports our future offerings such as application hosting and AI web application generation services. It is essential for specific commercial uses that go beyond the scope of the Apache 2.0 License.

While the Apache 2.0 License covers most commercial applications, a commercial license is necessary for:

- Application Hosting Services
- AI Web Application Generation Services

We value your understanding and support as we work to improve Yao for the entire community. By respecting these licensing terms, you help us allocate more resources to develop and maintain Yao, ensuring it remains a robust tool for everyone.

👉 **[Yao Commercial License](https://github.com/YaoApp/yao/blob/main/COMMERCIAL_LICENSE.md)**