})
Try Waspello here! | See the code
We've built a Trello clone using Wasp! Read on to learn how it went and how you can contribute.Waspello in action!
As you can see things work, but not everything is perfect (e.g. there is a delay when creating/moving a card) - we'll examine why is that so a bit later. ### Under the hood π π§ Here is a simple visual overview of Waspello's code anatomy (which applies to every Wasp app): Waspello code anatomy
Let's now dig in a bit deeper and shortly examine each of the concepts Wasp supports (page, query, entity, ...) and learn through code samples how to use it to implement Waspello. #### Entities It all starts with a data model definition (called `entity` in Wasp), which is defined via Prisma Schema Language: ```js title="main.wasp | Defining entities via Prisma Schema Language" // Entities entity User {=psl id Int @id @default(autoincrement()) username String @unique password String lists List[] cards Card[] psl=} entity List {=psl id Int @id @default(autoincrement()) name String pos Float // List has a single author. user User @relation(fields: [userId], references: [id]) userId Int cards Card[] psl=} entity Card {=psl id Int @id @default(autoincrement()) title String pos Float // Card belongs to a single list. list List @relation(fields: [listId], references: [id]) listId Int // Card has a single author. author User @relation(fields: [authorId], references: [id]) authorId Int psl=} ``` Those three entities are all we need! Wasp uses Prisma to create a database schema underneath and allows the developer to query it through its generated SDK. #### Queries and Actions (Operations) After we've defined our data models, the next step is to do something with them! We can read/create/update/delete an entity and that is what `query` and `action` mechanisms are for. Below follows an example from the Waspello code that demonstrates how it works. The first step is to declare to Wasp there will be a query, point to the actual function containing the query logic, and state from which entities it will be reading information: ```js title="main.wasp | Declaration of a query in Wasp" query getListsAndCards { // Points to the function which contains query logic. fn: import { getListsAndCards } from "@server/queries.js", // This query depends on List and Card entities. // If any of them changes this query will get re-fetched (cache invalidation). entities: [List, Card] } ``` The main point of this declaration is for Wasp to be aware of the query and thus be able to **do a lot of heavy lifting for us - e.g. it will make the query available to the client without any extra code**, all that developer needs to do is import it in their React component. **Another big thing is cache invalidation / automatic re-fetching of the query once the data changes** (this is why it is important to declare which entities it depends on). The remaining step is to write the function with the query logic: ```js title="src/server/queries.js | Query logic, using Prisma SDK via Node.js" export const getListsAndCards = async (args, context) => { // Only authenticated users can execute this query. if (!context.user) { throw new HttpError(403) } return context.entities.List.findMany({ // We want to make sure user can access only their own cards. where: { user: { id: context.user.id } }, include: { cards: true } }) } ``` This is just a regular Node.js function, there are no limits on what you can return! All the stuff provided by Wasp (user data, Prisma SDK for a specific entity) comes in a `context` variable. The code for actions is very similar (we just need to use `action` keyword instead of `query`) so I won't repeat it here. You can check out the code for `updateCard` action [here](https://github.com/wasp-lang/wasp/blob/release/examples/waspello/main.wasp#L103). #### Pages, routing & components To display all the nice data we have, we'll use React components. There are no limits to how you can use React components within Wasp, the only one is that each `page` has its root component: ```js title="main.wasp | Declaration of a page & route in Wasp" route MainRoute { path: "/", to: Main } page Main { authRequired: true, component: import Main from "@client/MainPage.js" } ``` All pretty straightforward so far! As you can see here, Wasp also provides [authentication out-of-the-box](/docs/language/features#authentication--authorization). Currently, the majority of the client logic of Waspello is contained in `src/client/MainPage.js` (we should break it down a little π - [you can help us!](https://github.com/wasp-lang/wasp/issues/334)). Just to give you an idea, here's a quick glimpse into it: ```js title="src/client/MainPage.js | Using React component in Wasp" // "Special" imports provided by Wasp. import { useQuery } from '@wasp/queries' import getListsAndCards from '@wasp/queries/getListsAndCards' import createList from '@wasp/actions/createList' const MainPage = ({ user }) => { // Fetching data via useQuery. const { data: listsAndCards, isFetchingListsAndCards, errorListsAndCards } = useQuery(getListsAndCards) // A lot of data transformations and sub components. ... // Display lists and cards. return ( ... ) } ``` Once you've defined a query or action as described above, you can immediately import it into your client code as shown in the code sample, by using the `@wasp` prefix in the import path. `useQuery` ensures reactivity so once the data changes the query will get re-fetched. You can find more details about it [here](/docs/language/features#usequery). This is pretty much it from the stuff that works π ! I kinda rushed a bit through things here - for more details on all Wasp features and to build your first app with Wasp, check out our [docs](/docs/). ## What doesn't work (yet) The main problem of the current implementation of Waspello is the **lack of support for optimistic UI updates in Wasp**. What this means is that currently, when an entity-related change is made (e.g. a card is moved from one list to another), we have to wait until that change is fully executed on the server until it is visible in the UI, which causes a noticeable delay. In many cases that is not an issue, but when UI elements are all visible at once and it is expected from them to be updated immediately, then it is noticeable. This is also one of the main reasons why we chose to work on Waspello - to have a benchmark/sandbox for this feature! Due to this issue, here's how things currently look like:
})