Docs update for Hacktoberfest

CONTRIBUTING.md

@@ -1 +1,58 @@
-Check [waspc README](waspc) for detailed contributing guidelines.
+# Contributing to Wasp
+
+Wasp's compiler is built with Haskell. As an output, you'll get a web application written in React and NodeJS. So there are three ways for you to contribute: 
+- [Haskell-related](#haskell-related)
+- [Web dev](#web-dev) (React, Node, HTML/CSS, database and so on)
+- [Tutorials or Example apps](#tutorials-or-example-apps)
+- [Documentation](#documentation)
+
+## Before you begin 
+
+- Check the [**Getting Started**](https://wasp-lang.dev/docs) guide to get familiar with Wasp's fundamentals. And ideally, build an app from the [**Pick a Tutorial**](https://wasp-lang.dev/docs/pick-a-tutorial) page
+- Figure out what you'd like to help with. It can be code, documentation, tutorials, etc. More on this is below.
+- Join our Discord [![**Discord**](https://img.shields.io/discord/686873244791210014?label=chat%20on%20discord)](https://discord.gg/rzdnErX) for faster communication and feedback. Also, we'll be glad to help you find the issue you'll enjoy working on, depending on your skill set!
+
+Let's jump right in!
+
+---
+
+## Haskell-related
+
+Wasp compiler is implemented in Haskell, but you will also see a lot of Javascript and other web technologies because the Wasp compiler transpilers Wasp code into them.
+
+You don't have to be an expert in Haskell to contribute or understand the code since we don't use complicated Haskell features much -> most of the code is relatively straightforward, and we are happy to help with the part that is not.
+
+Check the [**Wasp compiler README**](https://github.com/wasp-lang/wasp/blob/main/waspc/README.md) for all the detailed instructions and guides.
+
+[**Haskell-related issues can be found here.**](https://github.com/wasp-lang/wasp/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+label%3Ahaskell) 
+
+Feel free to contact us via Discord to ask for an appropriate issue for yourself. Or create new issues directly to work on them.
+
+---
+
+## Web dev
+
+Wasp is a language for developing full-stack web apps. This means there are plenty of tasks related to web development itself. 
+
+[**Web dev issues can be found here.**](https://github.com/wasp-lang/wasp/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+label%3Awebdev)
+
+---
+
+## Tutorials or Example apps
+
+Another great way to help is to create an app with Wasp! We have an [Examples](https://wasp-lang.dev/docs/examples) section on our website. As well as the [Tutorials](https://wasp-lang.dev/docs/pick-a-tutorial) page. Both those sections can be improved and updated with your projects. 
+
+All that's required is to create an app. And make a tutorial or a blog post to help other people reproduce your work. Some prominent examples are: [Waspello](https://wasp-lang.dev/blog/2021/12/02/waspello), [Waspleau](https://wasp-lang.dev/blog/2022/01/27/waspleau), [It Wasps on My Machine](https://wasp-lang.dev/blog/2022/09/05/dev-excuses-app-tutrial) and [To-Do app](https://wasp-lang.dev/docs/tutorials/todo-app).
+
+Or you can re-build your existing pet project with Wasp. That would be cool!
+
+---
+
+## Documentation
+
+It's the simplest one — a perfect fit for people without coding skills. If you've found an issue or a broken link or any other problems on our [website](https://wasp-lang.dev/) - please, feel free to improve :)
+
+[**Documentation issues can be found here.**](https://github.com/wasp-lang/wasp/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+label%3Adocumentation)
+
+
+Happy hacking!

web/docs/contributing.md

@@ -4,9 +4,14 @@ sidebar_label: Contributing
 slug: /contributing
 ---
 
-Any way you want to contribute is a good way, and we are happy to meet you :)!
+Any way you want to contribute is a good way, and we are happy to meet you! A single entry point for all contributors is the [CONTRIBUTING.md](https://github.com/wasp-lang/wasp/blob/main/CONTRIBUTING.md) file in our Github repo. All the requirements and instructions are there. So please check [CONTRIBUTING.md](https://github.com/wasp-lang/wasp/blob/main/CONTRIBUTING.md) for more details.
 
-Some typical ways to contribute:
-1. Join us on discord [![Discord](https://img.shields.io/discord/686873244791210014?label=chat%20on%20discord)](https://discord.gg/rzdnErX) and let's talk! We can discuss language design, new/existing features, weather, or you can just tell us how you feel about Wasp :).
-2. If there is something in docs that you think could be improved or clarified, go to [docs Github repo](https://github.com/wasp-lang/wasp) and make an issue/PR! Or, you can do it directly from here by clicking on "edit this page" at the bottom of each page.
-3. Create an issue/PR on [core Wasp repo](https://github.com/wasp-lang/wasp) to contribute directly to the language and/or compiler! Check [wapsc README](https://github.com/wasp-lang/wasp/tree/main/waspc) for more details.
+Some side notes to make your journey easier:
+
+1. Join us on discord [![Discord](https://img.shields.io/discord/686873244791210014?label=chat%20on%20discord)](https://discord.gg/rzdnErX) and let's talk! We can discuss language design, new/existing features, and weather, or you can tell us how you feel about Wasp :).
+
+2. Wasp's compiler is built with Haskell. So you'll need to be somewhat familiar with this language if you'd like to contribute to the compiler itself. If you don't have Haskell knowledge (or any dev experience at all) - no problem. There are a lot of JS-related tasks and documentation updates as well!
+
+3. If there's something you'd like to bring to our attention, go to [docs Github repo](https://github.com/wasp-lang/wasp) and make an issue/PR!
+
+Happy hacking!

web/docs/getting-started.md

@@ -123,7 +123,7 @@ That's it :tada:! You have successfully created and served a new web app at <htt
 
 ## 4. What next?
 
-**Check out the 🤓 [Todo App tutorial](tutorials/todo-app.md) 🤓 , which will take you through all the core features of Wasp!**
+**Check out the 🤓 [Pick a Tutorial page](pick-a-tutorial.md) 🤓. Choose an app, that you'd like to build. And it will take you through all the core features of Wasp!**
 
 You can also:
 - Join the community on [Discord](https://discord.gg/rzdnErX)! Any feedback or questions you have, we are there for you.

web/docs/pick-a-tutorial.md

@@ -0,0 +1,17 @@
+---
+title: Pick a Tutorial
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+Congrats, you're now familiar with the basic concepts of Wasp! 🥳 
+
+It's time to build something cool and check the capabilities of Wasp in action. Pick one of the app tutorials (there will be more of them with time) and leave us your impressions on Discord [![Discord](https://img.shields.io/discord/686873244791210014?label=chat%20on%20discord)](https://discord.gg/rzdnErX)
+
+<img alt="Let's build!"
+ src={useBaseUrl('img/develop-an-app.jpg')}
+ style={{ border: "1px solid black" }}
+ height="400px"
+/>
+
+P.S: If you decide to build another app on your own - we'd love to see that! If it's simple enough, let's turn it into a tutorial! Please check our [contribution guide](contributing) for detailed instructions and reach us on Discord. 

web/docs/tutorials/dev-excuses-app.md

@@ -0,0 +1,24 @@
+---
+title: Introduction
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+:::info
+Make sure you've set up Wasp! Check out [Getting Started](/getting-started.md) first for installation instructions, and then continue with the tutorial. In case of any issues - please, ping us on Discord [![Discord](https://img.shields.io/discord/686873244791210014?label=chat%20on%20discord)](https://discord.gg/rzdnErX). 
+:::
+
+We’ll build a web app to solve every developer's most common problem – finding an excuse to justify our messy work! And will do it with a single config file that covers the full-stack app architecture plus several dozen lines of code. In the quickest possible way, so we can’t excuse ourselves from building it!
+
+We’ll use Michele Gerarduzzi’s [open-source project](https://github.com/michelegera/devexcuses-api). It provides a simple API and a solid number of predefined excuses. A perfect fit for our needs. Let’s define the requirements for the project: 
+
+- The app should be able to pull excuses data from a public API. 
+- Save the ones you liked (and your boss doesn't) to the database for future reference.
+- Building an app shouldn’t take more than 15 minutes.
+- Use modern web dev technologies (NodeJS + React)
+
+As a result – we’ll get a simple and fun pet project. You can find the complete codebase [here](https://github.com/wasp-lang/wasp/tree/main/examples/tutorials/ItWaspsOnMyMachine). 
+
+<img alt="Final result"
+ src={useBaseUrl('img/dev-excuses-live-preview.gif')}
+/>

web/docs/tutorials/dev-excuses-app/adding-operations.md

@@ -0,0 +1,40 @@
+---
+title: Adding operations
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+Now you'll need to create two files: `actions.js` and `queries.js` in the `ext` folder.
+
+Let’s add `saveExcuse()` action to our `actions.js` file. This action will save the text of our excuse to the database. 
+
+```js title=".../ext/actions.js | Defining an action"
+export const saveExcuse = async (excuse, context) => {
+ return context.entities.Excuse.create({
+ data: { text: excuse.text }
+ })
+}
+```
+
+Then we need to create two queries in the `queries.js` file. First, one `getExcuse` will call an external API and fetch a new excuse. The second one, named `getAllSavedExcuses`, will pull all the excuses we’ve saved to our database. 
+
+```js title=".../ext/queries.js | Defining queries"
+import axios from 'axios';
+
+export const getExcuse = async () => {
+ return axios
+ .get('https://api.devexcus.es/')
+ .then(res => {
+ return res.data;
+ })
+ .catch(error => {
+ console.error(error);
+ });
+}
+
+export const getAllSavedExcuses = async (_args, context) => {
+ return context.entities.Excuse.findMany()
+}
+```
+
+That’s it! We finished our back-end. 🎉 Now, let’s use those queries/actions on our UI.

web/docs/tutorials/dev-excuses-app/creating-the-project.md

@@ -0,0 +1,27 @@
+---
+title: Creating the project
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+By now you're already know, [how to create a project and do have Wasp installed](/getting-started.md). So let’s create a new web app project named `ItWaspsOnMyMachine`.
+
+```
+wasp new ItWaspsOnMyMachine
+```
+
+Changing the working directory:
+```
+cd ItWaspsOnMyMachine
+```
+
+Starting the app:
+```
+wasp start
+```
+
+Now your default browser should open up with a simple predefined text message. That’s it! 🥳 For now – the codebase consists of only two files! `main.wasp` is the config file that defines the application’s functionality. And `MainPage.js` is the front-end. Everything else, like `Main.css` can be ignored.
+
+<img alt="Initial page"
+ src={useBaseUrl('img/init-page.png')}
+/>

web/docs/tutorials/dev-excuses-app/modifying-main-wasp-file.md

@@ -0,0 +1,102 @@
+---
+title: Modifying main.wasp file
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+First and foremost, we need to add some dependencies and introduce operations to our project. We’ll add Tailwind to make our UI more pretty and Axios for making API requests. 
+
+Also, we’ll declare a database entity called `Excuse`, queries, and action. The `Excuse` entity consists of the entity’s ID and the text. 
+
+`Queries` are here when we need to fetch/read something, while `actions` are here when we need to change/update data. Both query and action declaration consists of two lines – a reference to the file that contains implementation and a data model to operate on. You can find more info [in the docs section below](language/features#queries-and-actions-aka-operations). So let’s proceed. 
+
+Please, add this section to the `main.wasp` file's `app` section. 
+
+```js title="main.wasp | Adding dependencies"
+ head: [
+ "<script src='https://cdn.tailwindcss.com'></script>"
+ ],
+
+ dependencies: [ 
+ ("axios", "^0.21.1")
+ ]
+```
+
+Then add Excuse entity to the bottom of the file. Also you'll need to define queries and an action.
+
+```js title="main.wasp | Defining Excuse entity, queries and action"
+entity Excuse {=psl 
+ id Int @id @default(autoincrement())
+ text String
+psl=}
+
+query getExcuse { 
+ fn: import { getExcuse } from "@ext/queries.js",
+ entities: [Excuse]
+}
+
+query getAllSavedExcuses { 
+ fn: import { getAllSavedExcuses } from "@ext/queries.js",
+ entities: [Excuse]
+}
+
+action saveExcuse { 
+ fn: import { saveExcuse } from "@ext/actions.js",
+ entities: [Excuse]
+}
+```
+The resulting `main.wasp` file should look like this:
+
+```js title="main.wasp | Final result"
+
+// Main declaration, defines a new web app.
+app ItWaspsOnMyMachine {
+
+ // Used as a browser tab title. 
+ title: "It Wasps On My Machine",
+
+ head: [
+ // Adding Tailwind to make our UI prettier
+ "<script src='https://cdn.tailwindcss.com'></script>"
+ ],
+
+ dependencies: [ 
+ // Adding Axios for making HTTP requests 
+ ("axios", "^0.21.1")
+ ]
+}
+
+// Render page MainPage on url `/` (default url).
+route RootRoute { path: "/", to: MainPage } 
+
+// ReactJS implementation of our page located in `ext/MainPage.js` as a default export
+page MainPage { 
+ component: import Main from "@ext/MainPage.js"
+}
+
+// Prisma database entity
+entity Excuse {=psl 
+ id Int @id @default(autoincrement())
+ text String
+psl=}
+
+// Query declaration to get a new excuse
+query getExcuse { 
+ fn: import { getExcuse } from "@ext/queries.js",
+ entities: [Excuse]
+}
+
+// Query declaration to get all excuses
+query getAllSavedExcuses { 
+ fn: import { getAllSavedExcuses } from "@ext/queries.js",
+ entities: [Excuse]
+}
+
+// Action to save current excuse
+action saveExcuse { 
+ fn: import { saveExcuse } from "@ext/actions.js",
+ entities: [Excuse]
+}
+```
+
+Perfect! We've set up all the infrastruction. Now let's add some logic. 

web/docs/tutorials/dev-excuses-app/perform-migration-and-run.md

@@ -0,0 +1,39 @@
+---
+title: Perform migration and run the app
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+Before starting an app – we need to execute database migration because we changed the DB schema by adding new entities. If you’ve had something running in the terminal – stop it and run:
+
+```
+wasp db migrate-dev
+```
+
+You’ll be prompted to enter a name for the migration. Something like `init` will be ok. Now we can start the application!
+
+```
+wasp start
+```
+<img alt="Final empty result"
+ src={useBaseUrl('img/final-result.png')}
+/>
+
+Now you can click the “Get excuse” button to receive an excuse. And save the ones you like into the DB with the “Save excuse” button. Our final project should look like this:
+
+<img alt="Final result"
+ src={useBaseUrl('img/final-excuse-app.png')}
+/>
+
+Now we can think of some additional improvements. For example:
+
+- Add a unique constraint to Entity’s ID so we won’t be able to save duplicated excuses. 
+- Add exceptions and edge cases handling. 
+- Make the markup prettier.
+- Optimize and polish the code 
+
+So, we’ve been able to build a full-stack application with a database and external API call in a couple of minutes. And now we have a box full of excuses for all our development needs. 
+
+<img alt="Box of excuses for the win!"
+ src={useBaseUrl('img/accessible-website-excuse.jpg')}
+/>