diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index 4636f348da..0000000000 Binary files a/.DS_Store and /dev/null differ diff --git a/404.html b/404.html index e150f75e04..2a5b51caa5 100644 --- a/404.html +++ b/404.html @@ -19,13 +19,13 @@ - - + + -
-
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- - +
+
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

+ + \ No newline at end of file diff --git a/assets/js/03bfeeae.c5e28e91.js b/assets/js/03bfeeae.c5e28e91.js deleted file mode 100644 index 1599e45ec0..0000000000 --- a/assets/js/03bfeeae.c5e28e91.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[6692],{85162:(e,t,n)=>{n.d(t,{Z:()=>o});var a=n(67294),r=n(86010);const i={tabItem:"tabItem_Ymn6"};function o(e){let{children:t,hidden:n,className:o}=e;return a.createElement("div",{role:"tabpanel",className:(0,r.Z)(i.tabItem,o),hidden:n},t)}},74866:(e,t,n)=>{n.d(t,{Z:()=>N});var a=n(87462),r=n(67294),i=n(86010),o=n(12466),s=n(16550),l=n(91980),u=n(67392),c=n(50012);function p(e){return function(e){return r.Children.map(e,(e=>{if(!e||(0,r.isValidElement)(e)&&function(e){const{props:t}=e;return!!t&&"object"==typeof t&&"value"in t}(e))return e;throw new Error(`Docusaurus error: Bad child <${"string"==typeof e.type?e.type:e.type.name}>: all children of the component should be , and every should have a unique "value" prop.`)}))?.filter(Boolean)??[]}(e).map((e=>{let{props:{value:t,label:n,attributes:a,default:r}}=e;return{value:t,label:n,attributes:a,default:r}}))}function d(e){const{values:t,children:n}=e;return(0,r.useMemo)((()=>{const e=t??p(n);return function(e){const t=(0,u.l)(e,((e,t)=>e.value===t.value));if(t.length>0)throw new Error(`Docusaurus error: Duplicate values "${t.map((e=>e.value)).join(", ")}" found in . Every value needs to be unique.`)}(e),e}),[t,n])}function m(e){let{value:t,tabValues:n}=e;return n.some((e=>e.value===t))}function v(e){let{queryString:t=!1,groupId:n}=e;const a=(0,s.k6)(),i=function(e){let{queryString:t=!1,groupId:n}=e;if("string"==typeof t)return t;if(!1===t)return null;if(!0===t&&!n)throw new Error('Docusaurus error: The component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".');return n??null}({queryString:t,groupId:n});return[(0,l._X)(i),(0,r.useCallback)((e=>{if(!i)return;const t=new URLSearchParams(a.location.search);t.set(i,e),a.replace({...a.location,search:t.toString()})}),[i,a])]}function f(e){const{defaultValue:t,queryString:n=!1,groupId:a}=e,i=d(e),[o,s]=(0,r.useState)((()=>function(e){let{defaultValue:t,tabValues:n}=e;if(0===n.length)throw new Error("Docusaurus error: the component requires at least one children component");if(t){if(!m({value:t,tabValues:n}))throw new Error(`Docusaurus error: The has a defaultValue "${t}" but none of its children has the corresponding value. Available values are: ${n.map((e=>e.value)).join(", ")}. If you intend to show no default tab, use defaultValue={null} instead.`);return t}const a=n.find((e=>e.default))??n[0];if(!a)throw new Error("Unexpected error: 0 tabValues");return a.value}({defaultValue:t,tabValues:i}))),[l,u]=v({queryString:n,groupId:a}),[p,f]=function(e){let{groupId:t}=e;const n=function(e){return e?`docusaurus.tab.${e}`:null}(t),[a,i]=(0,c.Nk)(n);return[a,(0,r.useCallback)((e=>{n&&i.set(e)}),[n,i])]}({groupId:a}),g=(()=>{const e=l??p;return m({value:e,tabValues:i})?e:null})();(0,r.useLayoutEffect)((()=>{g&&s(g)}),[g]);return{selectedValue:o,selectValue:(0,r.useCallback)((e=>{if(!m({value:e,tabValues:i}))throw new Error(`Can't select invalid tab value=${e}`);s(e),u(e),f(e)}),[u,f,i]),tabValues:i}}var g=n(72389);const h={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};function b(e){let{className:t,block:n,selectedValue:s,selectValue:l,tabValues:u}=e;const c=[],{blockElementScrollPositionUntilNextRender:p}=(0,o.o5)(),d=e=>{const t=e.currentTarget,n=c.indexOf(t),a=u[n].value;a!==s&&(p(t),l(a))},m=e=>{let t=null;switch(e.key){case"Enter":d(e);break;case"ArrowRight":{const n=c.indexOf(e.currentTarget)+1;t=c[n]??c[0];break}case"ArrowLeft":{const n=c.indexOf(e.currentTarget)-1;t=c[n]??c[c.length-1];break}}t?.focus()};return r.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,i.Z)("tabs",{"tabs--block":n},t)},u.map((e=>{let{value:t,label:n,attributes:o}=e;return r.createElement("li",(0,a.Z)({role:"tab",tabIndex:s===t?0:-1,"aria-selected":s===t,key:t,ref:e=>c.push(e),onKeyDown:m,onClick:d},o,{className:(0,i.Z)("tabs__item",h.tabItem,o?.className,{"tabs__item--active":s===t})}),n??t)})))}function k(e){let{lazy:t,children:n,selectedValue:a}=e;const i=(Array.isArray(n)?n:[n]).filter(Boolean);if(t){const e=i.find((e=>e.props.value===a));return e?(0,r.cloneElement)(e,{className:"margin-top--md"}):null}return r.createElement("div",{className:"margin-top--md"},i.map(((e,t)=>(0,r.cloneElement)(e,{key:t,hidden:e.props.value!==a}))))}function y(e){const t=f(e);return r.createElement("div",{className:(0,i.Z)("tabs-container",h.tabList)},r.createElement(b,(0,a.Z)({},e,t)),r.createElement(k,(0,a.Z)({},e,t)))}function N(e){const t=(0,g.Z)();return r.createElement(y,(0,a.Z)({key:String(t)},e))}},46300:(e,t,n)=>{n.d(t,{Z:()=>i});var a=n(67294),r=n(50012);function i(e){let{path:t}=e;const[n]=(0,r.Nk)("docusaurus.tab.js-ts"),i=t.lastIndexOf("{"),o=t.slice(i+1,t.length-1),[s,l]=o.split(","),u=t.slice(0,i);return a.createElement("code",null,u+("js"===n?s:l))}},48863:(e,t,n)=>{n.d(t,{A:()=>o,v:()=>s});var a=n(67294),r=n(50012),i=n(49875);function o(e){let{children:t}=e;const[n]=(0,r.Nk)("docusaurus.tab.js-ts");return"ts"===n&&a.createElement(i.Z,null,t)}function s(e){let{children:t}=e;const[n]=(0,r.Nk)("docusaurus.tab.js-ts");return"js"===n&&a.createElement(i.Z,null,t)}},27582:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>l,default:()=>v,frontMatter:()=>s,metadata:()=>u,toc:()=>p});var a=n(87462),r=(n(67294),n(3905)),i=(n(46300),n(85162)),o=n(74866);n(48863);const s={title:"Custom Vite Config"},l=void 0,u={unversionedId:"project/custom-vite-config",id:"version-0.11.8/project/custom-vite-config",title:"Custom Vite Config",description:"Wasp uses Vite for serving the client during development and bundling it for production. If you want to customize the Vite config, you can do that by editing the vite.config.ts file in your src/client directory.",source:"@site/versioned_docs/version-0.11.8/project/custom-vite-config.md",sourceDirName:"project",slug:"/project/custom-vite-config",permalink:"/docs/0.11.8/project/custom-vite-config",draft:!1,editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/versioned_docs/version-0.11.8/project/custom-vite-config.md",tags:[],version:"0.11.8",frontMatter:{title:"Custom Vite Config"},sidebar:"docs",previous:{title:"CSS Frameworks",permalink:"/docs/0.11.8/project/css-frameworks"},next:{title:"Overview",permalink:"/docs/0.11.8/advanced/deployment/overview"}},c={},p=[{value:"Examples",id:"examples",level:2},{value:"Changing the Dev Server Behaviour",id:"changing-the-dev-server-behaviour",level:3},{value:"Custom Dev Server Port",id:"custom-dev-server-port",level:3},{value:"Customising the Base Path",id:"customising-the-base-path",level:3}],d={toc:p},m="wrapper";function v(e){let{components:t,...n}=e;return(0,r.kt)(m,(0,a.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"Wasp uses ",(0,r.kt)("a",{parentName:"p",href:"https://vitejs.dev/"},"Vite")," for serving the client during development and bundling it for production. If you want to customize the Vite config, you can do that by editing the ",(0,r.kt)("inlineCode",{parentName:"p"},"vite.config.ts")," file in your ",(0,r.kt)("inlineCode",{parentName:"p"},"src/client")," directory."),(0,r.kt)("p",null,"Wasp will use your config and ",(0,r.kt)("strong",{parentName:"p"},"merge")," it with the default Wasp's Vite config."),(0,r.kt)("p",null,"Vite config customization can be useful for things like:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Adding custom Vite plugins."),(0,r.kt)("li",{parentName:"ul"},"Customising the dev server."),(0,r.kt)("li",{parentName:"ul"},"Customising the build process.")),(0,r.kt)("p",null,"Be careful with making changes to the Vite config, as it can break the Wasp's client build process. Check out the default Vite config ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/wasp-lang/wasp/blob/main/waspc/data/Generator/templates/react-app/vite.config.ts"},"here")," to see what you can change."),(0,r.kt)("h2",{id:"examples"},"Examples"),(0,r.kt)("p",null,"Below are some examples of how you can customize the Vite config."),(0,r.kt)("h3",{id:"changing-the-dev-server-behaviour"},"Changing the Dev Server Behaviour"),(0,r.kt)("p",null,"If you want to stop Vite from opening the browser automatically when you run ",(0,r.kt)("inlineCode",{parentName:"p"},"wasp start"),", you can do that by customizing the ",(0,r.kt)("inlineCode",{parentName:"p"},"open")," option."),(0,r.kt)(o.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="src/client/vite.config.js"',title:'"src/client/vite.config.js"'},"export default {\n server: {\n open: false,\n },\n}\n"))),(0,r.kt)(i.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/client/vite.config.ts"',title:'"src/client/vite.config.ts"'},"import { defineConfig } from 'vite'\n\nexport default defineConfig({\n server: {\n open: false,\n },\n})\n")))),(0,r.kt)("h3",{id:"custom-dev-server-port"},"Custom Dev Server Port"),(0,r.kt)("p",null,"You have access to all of the ",(0,r.kt)("a",{parentName:"p",href:"https://vitejs.dev/config/server-options.html"},"Vite dev server options")," in your custom Vite config. You can change the dev server port by setting the ",(0,r.kt)("inlineCode",{parentName:"p"},"port")," option."),(0,r.kt)(o.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="src/client/vite.config.js"',title:'"src/client/vite.config.js"'},"export default {\n server: {\n port: 4000,\n },\n}\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-env",metastring:'title=".env.server"',title:'".env.server"'},"WASP_WEB_CLIENT_URL=http://localhost:4000\n"))),(0,r.kt)(i.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/client/vite.config.ts"',title:'"src/client/vite.config.ts"'},"import { defineConfig } from 'vite'\n\nexport default defineConfig({\n server: {\n port: 4000,\n },\n})\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-env",metastring:'title=".env.server"',title:'".env.server"'},"WASP_WEB_CLIENT_URL=http://localhost:4000\n")))),(0,r.kt)("admonition",{title:"Changing the dev server port",type:"warning"},(0,r.kt)("p",{parentName:"admonition"},"\u26a0\ufe0f Be careful when changing the dev server port, you'll need to update the ",(0,r.kt)("inlineCode",{parentName:"p"},"WASP_WEB_CLIENT_URL")," env var in your ",(0,r.kt)("inlineCode",{parentName:"p"},".env.server")," file.")),(0,r.kt)("h3",{id:"customising-the-base-path"},"Customising the Base Path"),(0,r.kt)("p",null,"If you, for example, want to serve the client from a different path than ",(0,r.kt)("inlineCode",{parentName:"p"},"/"),", you can do that by customizing the ",(0,r.kt)("inlineCode",{parentName:"p"},"base")," option."),(0,r.kt)(o.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="src/client/vite.config.js"',title:'"src/client/vite.config.js"'},"export default {\n base: '/my-app/',\n}\n"))),(0,r.kt)(i.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/client/vite.config.ts"',title:'"src/client/vite.config.ts"'},"import { defineConfig } from 'vite'\n\nexport default defineConfig({\n base: '/my-app/',\n})\n")))))}v.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/03bfeeae.c981005b.js b/assets/js/03bfeeae.c981005b.js new file mode 100644 index 0000000000..601dad72e0 --- /dev/null +++ b/assets/js/03bfeeae.c981005b.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[6692],{85162:(e,t,n)=>{n.d(t,{Z:()=>o});var a=n(67294),r=n(86010);const i={tabItem:"tabItem_Ymn6"};function o(e){let{children:t,hidden:n,className:o}=e;return a.createElement("div",{role:"tabpanel",className:(0,r.Z)(i.tabItem,o),hidden:n},t)}},74866:(e,t,n)=>{n.d(t,{Z:()=>N});var a=n(87462),r=n(67294),i=n(86010),o=n(12466),s=n(16550),l=n(91980),u=n(67392),c=n(50012);function p(e){return function(e){return r.Children.map(e,(e=>{if(!e||(0,r.isValidElement)(e)&&function(e){const{props:t}=e;return!!t&&"object"==typeof t&&"value"in t}(e))return e;throw new Error(`Docusaurus error: Bad child <${"string"==typeof e.type?e.type:e.type.name}>: all children of the component should be , and every should have a unique "value" prop.`)}))?.filter(Boolean)??[]}(e).map((e=>{let{props:{value:t,label:n,attributes:a,default:r}}=e;return{value:t,label:n,attributes:a,default:r}}))}function d(e){const{values:t,children:n}=e;return(0,r.useMemo)((()=>{const e=t??p(n);return function(e){const t=(0,u.l)(e,((e,t)=>e.value===t.value));if(t.length>0)throw new Error(`Docusaurus error: Duplicate values "${t.map((e=>e.value)).join(", ")}" found in . Every value needs to be unique.`)}(e),e}),[t,n])}function m(e){let{value:t,tabValues:n}=e;return n.some((e=>e.value===t))}function v(e){let{queryString:t=!1,groupId:n}=e;const a=(0,s.k6)(),i=function(e){let{queryString:t=!1,groupId:n}=e;if("string"==typeof t)return t;if(!1===t)return null;if(!0===t&&!n)throw new Error('Docusaurus error: The component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".');return n??null}({queryString:t,groupId:n});return[(0,l._X)(i),(0,r.useCallback)((e=>{if(!i)return;const t=new URLSearchParams(a.location.search);t.set(i,e),a.replace({...a.location,search:t.toString()})}),[i,a])]}function f(e){const{defaultValue:t,queryString:n=!1,groupId:a}=e,i=d(e),[o,s]=(0,r.useState)((()=>function(e){let{defaultValue:t,tabValues:n}=e;if(0===n.length)throw new Error("Docusaurus error: the component requires at least one children component");if(t){if(!m({value:t,tabValues:n}))throw new Error(`Docusaurus error: The has a defaultValue "${t}" but none of its children has the corresponding value. Available values are: ${n.map((e=>e.value)).join(", ")}. If you intend to show no default tab, use defaultValue={null} instead.`);return t}const a=n.find((e=>e.default))??n[0];if(!a)throw new Error("Unexpected error: 0 tabValues");return a.value}({defaultValue:t,tabValues:i}))),[l,u]=v({queryString:n,groupId:a}),[p,f]=function(e){let{groupId:t}=e;const n=function(e){return e?`docusaurus.tab.${e}`:null}(t),[a,i]=(0,c.Nk)(n);return[a,(0,r.useCallback)((e=>{n&&i.set(e)}),[n,i])]}({groupId:a}),g=(()=>{const e=l??p;return m({value:e,tabValues:i})?e:null})();(0,r.useLayoutEffect)((()=>{g&&s(g)}),[g]);return{selectedValue:o,selectValue:(0,r.useCallback)((e=>{if(!m({value:e,tabValues:i}))throw new Error(`Can't select invalid tab value=${e}`);s(e),u(e),f(e)}),[u,f,i]),tabValues:i}}var g=n(72389);const h={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};function b(e){let{className:t,block:n,selectedValue:s,selectValue:l,tabValues:u}=e;const c=[],{blockElementScrollPositionUntilNextRender:p}=(0,o.o5)(),d=e=>{const t=e.currentTarget,n=c.indexOf(t),a=u[n].value;a!==s&&(p(t),l(a))},m=e=>{let t=null;switch(e.key){case"Enter":d(e);break;case"ArrowRight":{const n=c.indexOf(e.currentTarget)+1;t=c[n]??c[0];break}case"ArrowLeft":{const n=c.indexOf(e.currentTarget)-1;t=c[n]??c[c.length-1];break}}t?.focus()};return r.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,i.Z)("tabs",{"tabs--block":n},t)},u.map((e=>{let{value:t,label:n,attributes:o}=e;return r.createElement("li",(0,a.Z)({role:"tab",tabIndex:s===t?0:-1,"aria-selected":s===t,key:t,ref:e=>c.push(e),onKeyDown:m,onClick:d},o,{className:(0,i.Z)("tabs__item",h.tabItem,o?.className,{"tabs__item--active":s===t})}),n??t)})))}function k(e){let{lazy:t,children:n,selectedValue:a}=e;const i=(Array.isArray(n)?n:[n]).filter(Boolean);if(t){const e=i.find((e=>e.props.value===a));return e?(0,r.cloneElement)(e,{className:"margin-top--md"}):null}return r.createElement("div",{className:"margin-top--md"},i.map(((e,t)=>(0,r.cloneElement)(e,{key:t,hidden:e.props.value!==a}))))}function y(e){const t=f(e);return r.createElement("div",{className:(0,i.Z)("tabs-container",h.tabList)},r.createElement(b,(0,a.Z)({},e,t)),r.createElement(k,(0,a.Z)({},e,t)))}function N(e){const t=(0,g.Z)();return r.createElement(y,(0,a.Z)({key:String(t)},e))}},48863:(e,t,n)=>{n.d(t,{A:()=>o,v:()=>s});var a=n(67294),r=n(50012),i=n(49875);function o(e){let{children:t}=e;const[n]=(0,r.Nk)("docusaurus.tab.js-ts");return"ts"===n&&a.createElement(i.Z,null,t)}function s(e){let{children:t}=e;const[n]=(0,r.Nk)("docusaurus.tab.js-ts");return"js"===n&&a.createElement(i.Z,null,t)}},27582:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>l,default:()=>v,frontMatter:()=>s,metadata:()=>u,toc:()=>p});var a=n(87462),r=(n(67294),n(3905)),i=n(85162),o=n(74866);n(48863);const s={title:"Custom Vite Config"},l=void 0,u={unversionedId:"project/custom-vite-config",id:"version-0.11.8/project/custom-vite-config",title:"Custom Vite Config",description:"Wasp uses Vite for serving the client during development and bundling it for production. If you want to customize the Vite config, you can do that by editing the vite.config.ts file in your src/client directory.",source:"@site/versioned_docs/version-0.11.8/project/custom-vite-config.md",sourceDirName:"project",slug:"/project/custom-vite-config",permalink:"/docs/0.11.8/project/custom-vite-config",draft:!1,editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/versioned_docs/version-0.11.8/project/custom-vite-config.md",tags:[],version:"0.11.8",frontMatter:{title:"Custom Vite Config"},sidebar:"docs",previous:{title:"CSS Frameworks",permalink:"/docs/0.11.8/project/css-frameworks"},next:{title:"Overview",permalink:"/docs/0.11.8/advanced/deployment/overview"}},c={},p=[{value:"Examples",id:"examples",level:2},{value:"Changing the Dev Server Behaviour",id:"changing-the-dev-server-behaviour",level:3},{value:"Custom Dev Server Port",id:"custom-dev-server-port",level:3},{value:"Customising the Base Path",id:"customising-the-base-path",level:3}],d={toc:p},m="wrapper";function v(e){let{components:t,...n}=e;return(0,r.kt)(m,(0,a.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"Wasp uses ",(0,r.kt)("a",{parentName:"p",href:"https://vitejs.dev/"},"Vite")," for serving the client during development and bundling it for production. If you want to customize the Vite config, you can do that by editing the ",(0,r.kt)("inlineCode",{parentName:"p"},"vite.config.ts")," file in your ",(0,r.kt)("inlineCode",{parentName:"p"},"src/client")," directory."),(0,r.kt)("p",null,"Wasp will use your config and ",(0,r.kt)("strong",{parentName:"p"},"merge")," it with the default Wasp's Vite config."),(0,r.kt)("p",null,"Vite config customization can be useful for things like:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Adding custom Vite plugins."),(0,r.kt)("li",{parentName:"ul"},"Customising the dev server."),(0,r.kt)("li",{parentName:"ul"},"Customising the build process.")),(0,r.kt)("p",null,"Be careful with making changes to the Vite config, as it can break the Wasp's client build process. Check out the default Vite config ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/wasp-lang/wasp/blob/main/waspc/data/Generator/templates/react-app/vite.config.ts"},"here")," to see what you can change."),(0,r.kt)("h2",{id:"examples"},"Examples"),(0,r.kt)("p",null,"Below are some examples of how you can customize the Vite config."),(0,r.kt)("h3",{id:"changing-the-dev-server-behaviour"},"Changing the Dev Server Behaviour"),(0,r.kt)("p",null,"If you want to stop Vite from opening the browser automatically when you run ",(0,r.kt)("inlineCode",{parentName:"p"},"wasp start"),", you can do that by customizing the ",(0,r.kt)("inlineCode",{parentName:"p"},"open")," option."),(0,r.kt)(o.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="src/client/vite.config.js"',title:'"src/client/vite.config.js"'},"export default {\n server: {\n open: false,\n },\n}\n"))),(0,r.kt)(i.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/client/vite.config.ts"',title:'"src/client/vite.config.ts"'},"import { defineConfig } from 'vite'\n\nexport default defineConfig({\n server: {\n open: false,\n },\n})\n")))),(0,r.kt)("h3",{id:"custom-dev-server-port"},"Custom Dev Server Port"),(0,r.kt)("p",null,"You have access to all of the ",(0,r.kt)("a",{parentName:"p",href:"https://vitejs.dev/config/server-options.html"},"Vite dev server options")," in your custom Vite config. You can change the dev server port by setting the ",(0,r.kt)("inlineCode",{parentName:"p"},"port")," option."),(0,r.kt)(o.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="src/client/vite.config.js"',title:'"src/client/vite.config.js"'},"export default {\n server: {\n port: 4000,\n },\n}\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-env",metastring:'title=".env.server"',title:'".env.server"'},"WASP_WEB_CLIENT_URL=http://localhost:4000\n"))),(0,r.kt)(i.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/client/vite.config.ts"',title:'"src/client/vite.config.ts"'},"import { defineConfig } from 'vite'\n\nexport default defineConfig({\n server: {\n port: 4000,\n },\n})\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-env",metastring:'title=".env.server"',title:'".env.server"'},"WASP_WEB_CLIENT_URL=http://localhost:4000\n")))),(0,r.kt)("admonition",{title:"Changing the dev server port",type:"warning"},(0,r.kt)("p",{parentName:"admonition"},"\u26a0\ufe0f Be careful when changing the dev server port, you'll need to update the ",(0,r.kt)("inlineCode",{parentName:"p"},"WASP_WEB_CLIENT_URL")," env var in your ",(0,r.kt)("inlineCode",{parentName:"p"},".env.server")," file.")),(0,r.kt)("h3",{id:"customising-the-base-path"},"Customising the Base Path"),(0,r.kt)("p",null,"If you, for example, want to serve the client from a different path than ",(0,r.kt)("inlineCode",{parentName:"p"},"/"),", you can do that by customizing the ",(0,r.kt)("inlineCode",{parentName:"p"},"base")," option."),(0,r.kt)(o.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="src/client/vite.config.js"',title:'"src/client/vite.config.js"'},"export default {\n base: '/my-app/',\n}\n"))),(0,r.kt)(i.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/client/vite.config.ts"',title:'"src/client/vite.config.ts"'},"import { defineConfig } from 'vite'\n\nexport default defineConfig({\n base: '/my-app/',\n})\n")))))}v.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/045ac00a.f11d8439.js b/assets/js/045ac00a.0c3c6d45.js similarity index 99% rename from assets/js/045ac00a.f11d8439.js rename to assets/js/045ac00a.0c3c6d45.js index c7a1d0e105..fe0b6b7a2e 100644 --- a/assets/js/045ac00a.f11d8439.js +++ b/assets/js/045ac00a.0c3c6d45.js @@ -1 +1 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[18],{3905:(e,t,a)=>{a.d(t,{Zo:()=>p,kt:()=>h});var n=a(67294);function o(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function s(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function r(e){for(var t=1;t=0||(o[a]=e[a]);return o}(e,t);if(Object.getOwnPropertySymbols){var s=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(o[a]=e[a])}return o}var l=n.createContext({}),u=function(e){var t=n.useContext(l),a=t;return e&&(a="function"==typeof e?e(t):r(r({},t),e)),a},p=function(e){var t=u(e.components);return n.createElement(l.Provider,{value:t},e.children)},c="mdxType",m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},d=n.forwardRef((function(e,t){var a=e.components,o=e.mdxType,s=e.originalType,l=e.parentName,p=i(e,["components","mdxType","originalType","parentName"]),c=u(a),d=o,h=c["".concat(l,".").concat(d)]||c[d]||m[d]||s;return a?n.createElement(h,r(r({ref:t},p),{},{components:a})):n.createElement(h,r({ref:t},p))}));function h(e,t){var a=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var s=a.length,r=new Array(s);r[0]=d;var i={};for(var l in t)hasOwnProperty.call(t,l)&&(i[l]=t[l]);i.originalType=e,i[c]="string"==typeof e?e:o,r[1]=i;for(var u=2;u{a.d(t,{Z:()=>s});var n=a(67294),o=a(44996);const s=e=>n.createElement("div",null,n.createElement("p",{align:"center"},n.createElement("figure",null,n.createElement("img",{style:{width:e.width},alt:e.alt,src:(0,o.Z)(e.source)}),n.createElement("figcaption",{class:"image-caption",style:{fontStyle:"italic",opacity:.6,fontSize:"0.9rem"}},e.caption))))},92908:(e,t,a)=>{a.d(t,{Z:()=>r});var n=a(67294),o=a(39960);a(44996);const s=()=>n.createElement("span",{className:"in-blog-cta--divider"}," \u2192 "),r=()=>n.createElement("p",{className:"in-blog-cta-link-container"},n.createElement(o.Z,{className:"in-blog-cta--link",to:"https://e44cy1h4s0q.typeform.com/to/ycUzQa5A"},"We are in Beta (try it out)!"),n.createElement(s,null),n.createElement(o.Z,{className:"in-blog-cta--link",to:"https://discord.gg/rzdnErX"},"Join our community"),n.createElement(s,null),n.createElement(o.Z,{className:"in-blog-cta--link",to:"https://wasp-lang.notion.site/Founding-Engineer-at-Wasp-402274568afa4d7eb7f428f8fa2c0816"},"Work with us"))},48238:(e,t,a)=>{a.r(t),a.d(t,{assets:()=>c,contentTitle:()=>u,default:()=>g,frontMatter:()=>l,metadata:()=>p,toc:()=>m});var n=a(87462),o=(a(67294),a(3905)),s=(a(39960),a(44996)),r=a(92908),i=a(70589);a(38610);const l={title:"Feature Announcement - Wasp Jobs",authors:["shayneczyzewski"],image:"/img/jobs-snippet2.png",tags:["webdev","wasp","feature","jobs"]},u=void 0,p={permalink:"/blog/2022/06/15/jobs-feature-announcement",editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/blog/2022-06-15-jobs-feature-announcement.md",source:"@site/blog/2022-06-15-jobs-feature-announcement.md",title:"Feature Announcement - Wasp Jobs",description:'You get a job!Storytime",id:"storytime",level:2},{value:"Most jobs have a boss. Our first job executor is a... pg-boss. \ud83d\ude05",id:"most-jobs-have-a-boss-our-first-job-executor-is-a-pg-boss-",level:2},{value:"Real Example - Updating Waspleau",id:"real-example---updating-waspleau",level:2},{value:"Looks neat! What\u2019s next?",id:"looks-neat-whats-next",level:2}],d={toc:m},h="wrapper";function g(e){let{components:t,...l}=e;return(0,o.kt)(h,(0,n.Z)({},d,l,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",{align:"center"},(0,o.kt)("img",{alt:"You get a job!",src:(0,s.Z)("img/jobs-oprah.gif"),width:"300px"})),(0,o.kt)(i.ZP,{mdxType:"WaspIntro"}),(0,o.kt)(r.Z,{mdxType:"InBlogCta"}),(0,o.kt)("h2",{id:"storytime"},(0,o.kt)("strong",{parentName:"h2"},"Storytime")),(0,o.kt)("p",{align:"center"},(0,o.kt)("img",{alt:"Storytime",src:(0,s.Z)("img/jobs-storytime.gif"),width:"300px"})),(0,o.kt)("p",null,"Imagine you are working on the next unicorn SaaS web app and need to send a user an email, manipulate an uploaded image via an external API call, or recalculate some internal metrics every night. (Or, maybe you\u2019re doing some fancy blockchain thing for that frothy investment multiple; :D whatever it is, just envision an operation that may take a significant amount of time and/or fail.) How would you implement this?"),(0,o.kt)("p",{align:"center"},(0,o.kt)("img",{alt:"Spinning!",src:(0,s.Z)("img/jobs-spinner.gif"),width:"30px"})),(0,o.kt)("p",null,"You wouldn\u2019t want the server to delay sending its HTTP response until those are done (unless you are one of those people who love seeing the Mac spinning icon), so you'll need something out-of-band from the normal request-response flow. Even in an event-loop-based system like Node.js, just calling an async function isn't ideal since you will need to handle failures, retries, and throttling, amongst other concerns. And sometimes we need to schedule tasks to run in the future, or repeatedly, so we need a completely different toolset."),(0,o.kt)("p",null,"The typical solution here is to use a job queue of some kind. They are not impossible to set up, of course, but there is a fair amount of boilerplate involved, some operational expertise/overhead required, and moving from one system to another when you outgrow it is usually a challenge. These are the exact areas where we feel Wasp can provide real value, so we are happy to introduce Wasp Jobs to help out with this!"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-js",metastring:"title=src/server/workers/github.js",title:"src/server/workers/github.js"},"import axios from 'axios'\nimport { upsertMetric } from './utils.js'\n\nexport async function workerFunction() {\n const response = await axios.get('https://api.github.com/repos/wasp-lang/wasp')\n\n const metrics = [\n { name: 'Wasp GitHub Stars', value: response.data.stargazers_count },\n { name: 'Wasp GitHub Language', value: response.data.language },\n { name: 'Wasp GitHub Forks', value: response.data.forks },\n { name: 'Wasp GitHub Open Issues', value: response.data.open_issues },\n ]\n\n await Promise.all(metrics.map(upsertMetric))\n\n return metrics\n}\n")),(0,o.kt)("p",null,"Wasp allows you to write a regular async JavaScript function (like the one above that gathers GitHub metrics and stores them in the DB) and have it run within the context of a job queue system, which we call an executor. You can manually submit work to be done on the server, or specify a cron schedule to have your job automatically invoked. And, best of all, as we add more job executors in the future, you can change where it runs on a single line in your .wasp file."),(0,o.kt)("h2",{id:"most-jobs-have-a-boss-our-first-job-executor-is-a-pg-boss-"},"Most jobs have a boss. Our first job executor is a... pg-boss. \ud83d\ude05"),(0,o.kt)("p",{align:"center"},(0,o.kt)("figure",null,(0,o.kt)("img",{alt:"Eeek",src:(0,s.Z)("img/jobs-eyes.gif")}),(0,o.kt)("figcaption",null,"Me trying to lay off the job-related puns. Ok, ok, I\u2019ll quit. Ahhh!"))),(0,o.kt)("p",null,"In my prior life as a Ruby on Rails developer, the decision of how to implement jobs was pretty simple. You had Active Job at your disposal, and for backends, you would use something like Sidekiq or Delayed Job. In a similarly paved path, Python developers would have likely looked first to Celery."),(0,o.kt)("p",null,"In the JavaScript world, ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/OptimalBits/bull"},"Bull")," is quite popular these days. However, we decided to use ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/timgit/pg-boss"},"pg-boss"),", as it too provides persistence, delayed jobs, and schedules (plus many other features). But critically, pg-boss uses PostgreSQL instead of Redis (like Bull) for storage and coordination, and this was important since we did not want to introduce any new infrastructure dependencies to our existing production stack."),(0,o.kt)("p",null,"But isn\u2019t a database as a queue an anti-pattern, you may ask? Well, historically I\u2019d probably say yes. However, PostgreSQL 9.5 added SKIP LOCKED, which it specifically mentions can aid in avoiding lock contention with multiple consumer queue-like workloads [",(0,o.kt)("a",{parentName:"p",href:"https://www.postgresql.org/docs/9.5/sql-select.html#SQL-FOR-UPDATE-SHARE"},"https://www.postgresql.org/docs/9.5/sql-select.html#SQL-FOR-UPDATE-SHARE"),"]. So for the low-volume background job workloads that many apps have, we feel using a database as a queue is a great compromise and starting point for many users from a benefit vs. complexity perspective."),(0,o.kt)("p",null,"However, we will also continue to expand the number of job execution runtimes we support. Let us know in ",(0,o.kt)("a",{parentName:"p",href:"https://discord.gg/rzdnErX"},"Discord")," what you\u2019d like to see next!"),(0,o.kt)("h2",{id:"real-example---updating-waspleau"},"Real Example - Updating Waspleau"),(0,o.kt)("p",null,"If you are a regular reader of this blog (thank you, you deserve a raise! \ud83d\ude0a), you may recall we created an example app of a metrics dashboard called ",(0,o.kt)("a",{parentName:"p",href:"https://wasp-lang.dev/blog/2022/01/27/waspleau"},"Waspleau")," that used workers in the background to make periodic HTTP calls for data. In that example, we didn\u2019t yet have access to recurring jobs in Wasp, so we used Bull for scheduled jobs instead. To set up our queue-related logic we had to have this huge ",(0,o.kt)("inlineCode",{parentName:"p"},"setupFn")," wiring it all up; but now, we can remove all that code and simply use jobs instead! Here is what the new DSL looks like:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-wasp",metastring:"title=main.wasp",title:"main.wasp"},'// A cron job for fetching GitHub stats\njob getGithubStats {\n executor: PgBoss,\n perform: {\n fn: import { workerFunction } from "@server/workers/github.js"\n },\n schedule: {\n cron: "*/10 * * * *"\n }\n}\n\n// A cron job to measure how long a webpage takes to load\njob calcPageLoadTime {\n executor: PgBoss,\n perform: {\n fn: import { workerFunction } from "@server/workers/loadTime.js"\n },\n schedule: {\n cron: "*/5 * * * *",\n args: {=json {\n "url": "https://wasp-lang.dev",\n "name": "wasp-lang.dev Load Time"\n } json=}\n }\n}\n')),(0,o.kt)("p",null,"And here is an example of how you can reference and invoke jobs on the server. ",(0,o.kt)("em",{parentName:"p"},"Note: We did not even need to do this step since jobs with a schedule are automatically configured to run at the desired time.")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-js",metastring:"title=src/server/serverSetup.js",title:"src/server/serverSetup.js"},"/**\n* These Jobs are automatically scheduled by Wasp.\n* However, let's kick them off on server setup to ensure we have data right away.\n*/\nimport { github } from '@wasp/jobs/getGithubStats.js'\nimport { loadTime } from '@wasp/jobs/calcPageLoadTime.js'\n\nexport default async function () {\n await github.submit()\n await loadTime.submit({\n url: \"https://wasp-lang.dev\",\n name: \"wasp-lang.dev Load Time\"\n })\n}\n")),(0,o.kt)("p",null,"And voila, it is really that simple. Wasp takes care of setting up pg-boss and hooking up all your job callbacks, leaving you to focus on what matters- your own code. Here is a visual of what is happening behind the scenes:"),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Architecture",src:a(84191).Z,width:"2626",height:"1452"})),(0,o.kt)("p",null,"For those interested, check out the ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/wasp-lang/wasp/commit/1721371fc73f4485ca0046aafea2ee3fc0be41cf#diff-e158328e137176b595ad01641ba68faf82dbb88ccc5be3597009bb576fcd6505"},"full diff here")," and weep with joy for all those boilerplate lines of code we fired! We were also able to ax Redis from our infrastructure!"),(0,o.kt)("h2",{id:"looks-neat-whats-next"},"Looks neat! What\u2019s next?"),(0,o.kt)("p",null,"First off, please check out our docs for ",(0,o.kt)("a",{parentName:"p",href:"/docs/advanced/jobs"},"Jobs"),". There, you will find all the info you need to start using them. Next, if you want to see the code for this example in full, you can find it here: ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/wasp-lang/wasp/tree/release/examples/waspleau"},"https://github.com/wasp-lang/wasp/tree/release/examples/waspleau")),(0,o.kt)("p",null,"In the future, we plan to add more job executors, including support for polyglot workers (imagine running your Python ML function from Wasp!). We are also open to any other ideas on how jobs can become more useful to you (like client-side access to server-side jobs, or client-side jobs using similar abstractions?). Let us know what you think!"),(0,o.kt)("hr",null),(0,o.kt)("small",null,"Special thanks to Tim Jones for his hard work building an amazing OSS library, ",(0,o.kt)("a",{href:"https://github.com/timgit/pg-boss",target:"_blank"},"pg-boss"),", and for reviewing this post. Please consider supporting that project if it solves your needs!"))}g.isMDXComponent=!0},70589:(e,t,a)=>{a.d(t,{ZP:()=>i});var n=a(87462),o=(a(67294),a(3905));const s={toc:[]},r="wrapper";function i(e){let{components:t,...a}=e;return(0,o.kt)(r,(0,n.Z)({},s,a,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,(0,o.kt)("em",{parentName:"p"},"Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.")))}i.isMDXComponent=!0},84191:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/jobs-arch-3ebc08ebc717194dfac7e67fca5b8a7d.png"}}]); \ No newline at end of file +"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[18],{3905:(e,t,a)=>{a.d(t,{Zo:()=>p,kt:()=>h});var n=a(67294);function o(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function s(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function r(e){for(var t=1;t=0||(o[a]=e[a]);return o}(e,t);if(Object.getOwnPropertySymbols){var s=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(o[a]=e[a])}return o}var l=n.createContext({}),u=function(e){var t=n.useContext(l),a=t;return e&&(a="function"==typeof e?e(t):r(r({},t),e)),a},p=function(e){var t=u(e.components);return n.createElement(l.Provider,{value:t},e.children)},c="mdxType",m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},d=n.forwardRef((function(e,t){var a=e.components,o=e.mdxType,s=e.originalType,l=e.parentName,p=i(e,["components","mdxType","originalType","parentName"]),c=u(a),d=o,h=c["".concat(l,".").concat(d)]||c[d]||m[d]||s;return a?n.createElement(h,r(r({ref:t},p),{},{components:a})):n.createElement(h,r({ref:t},p))}));function h(e,t){var a=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var s=a.length,r=new Array(s);r[0]=d;var i={};for(var l in t)hasOwnProperty.call(t,l)&&(i[l]=t[l]);i.originalType=e,i[c]="string"==typeof e?e:o,r[1]=i;for(var u=2;u{a.d(t,{Z:()=>s});var n=a(67294),o=a(44996);const s=e=>n.createElement("div",null,n.createElement("p",{align:"center"},n.createElement("figure",null,n.createElement("img",{style:{width:e.width},alt:e.alt,src:(0,o.Z)(e.source)}),n.createElement("figcaption",{class:"image-caption",style:{fontStyle:"italic",opacity:.6,fontSize:"0.9rem"}},e.caption))))},92908:(e,t,a)=>{a.d(t,{Z:()=>r});var n=a(67294),o=a(39960);a(44996);const s=()=>n.createElement("span",{className:"in-blog-cta--divider"}," \u2192 "),r=()=>n.createElement("p",{className:"in-blog-cta-link-container"},n.createElement(o.Z,{className:"in-blog-cta--link",to:"https://e44cy1h4s0q.typeform.com/to/ycUzQa5A"},"We are in Beta (try it out)!"),n.createElement(s,null),n.createElement(o.Z,{className:"in-blog-cta--link",to:"https://discord.gg/rzdnErX"},"Join our community"),n.createElement(s,null),n.createElement(o.Z,{className:"in-blog-cta--link",to:"https://wasp-lang.notion.site/Founding-Engineer-at-Wasp-402274568afa4d7eb7f428f8fa2c0816"},"Work with us"))},48238:(e,t,a)=>{a.r(t),a.d(t,{assets:()=>c,contentTitle:()=>u,default:()=>g,frontMatter:()=>l,metadata:()=>p,toc:()=>m});var n=a(87462),o=(a(67294),a(3905)),s=(a(39960),a(44996)),r=a(92908),i=a(70589);a(38610);const l={title:"Feature Announcement - Wasp Jobs",authors:["shayneczyzewski"],image:"/img/jobs-snippet2.png",tags:["webdev","wasp","feature","jobs"]},u=void 0,p={permalink:"/blog/2022/06/15/jobs-feature-announcement",editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/blog/2022-06-15-jobs-feature-announcement.md",source:"@site/blog/2022-06-15-jobs-feature-announcement.md",title:"Feature Announcement - Wasp Jobs",description:'You get a job!Storytime",id:"storytime",level:2},{value:"Most jobs have a boss. Our first job executor is a... pg-boss. \ud83d\ude05",id:"most-jobs-have-a-boss-our-first-job-executor-is-a-pg-boss-",level:2},{value:"Real Example - Updating Waspleau",id:"real-example---updating-waspleau",level:2},{value:"Looks neat! What\u2019s next?",id:"looks-neat-whats-next",level:2}],d={toc:m},h="wrapper";function g(e){let{components:t,...l}=e;return(0,o.kt)(h,(0,n.Z)({},d,l,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",{align:"center"},(0,o.kt)("img",{alt:"You get a job!",src:(0,s.Z)("img/jobs-oprah.gif"),width:"300px"})),(0,o.kt)(i.ZP,{mdxType:"WaspIntro"}),(0,o.kt)(r.Z,{mdxType:"InBlogCta"}),(0,o.kt)("h2",{id:"storytime"},(0,o.kt)("strong",{parentName:"h2"},"Storytime")),(0,o.kt)("p",{align:"center"},(0,o.kt)("img",{alt:"Storytime",src:(0,s.Z)("img/jobs-storytime.gif"),width:"300px"})),(0,o.kt)("p",null,"Imagine you are working on the next unicorn SaaS web app and need to send a user an email, manipulate an uploaded image via an external API call, or recalculate some internal metrics every night. (Or, maybe you\u2019re doing some fancy blockchain thing for that frothy investment multiple; :D whatever it is, just envision an operation that may take a significant amount of time and/or fail.) How would you implement this?"),(0,o.kt)("p",{align:"center"},(0,o.kt)("img",{alt:"Spinning!",src:(0,s.Z)("img/jobs-spinner.gif"),width:"30px"})),(0,o.kt)("p",null,"You wouldn\u2019t want the server to delay sending its HTTP response until those are done (unless you are one of those people who love seeing the Mac spinning icon), so you'll need something out-of-band from the normal request-response flow. Even in an event-loop-based system like Node.js, just calling an async function isn't ideal since you will need to handle failures, retries, and throttling, amongst other concerns. And sometimes we need to schedule tasks to run in the future, or repeatedly, so we need a completely different toolset."),(0,o.kt)("p",null,"The typical solution here is to use a job queue of some kind. They are not impossible to set up, of course, but there is a fair amount of boilerplate involved, some operational expertise/overhead required, and moving from one system to another when you outgrow it is usually a challenge. These are the exact areas where we feel Wasp can provide real value, so we are happy to introduce Wasp Jobs to help out with this!"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-js",metastring:"title=src/server/workers/github.js",title:"src/server/workers/github.js"},"import axios from 'axios'\nimport { upsertMetric } from './utils.js'\n\nexport async function workerFunction() {\n const response = await axios.get('https://api.github.com/repos/wasp-lang/wasp')\n\n const metrics = [\n { name: 'Wasp GitHub Stars', value: response.data.stargazers_count },\n { name: 'Wasp GitHub Language', value: response.data.language },\n { name: 'Wasp GitHub Forks', value: response.data.forks },\n { name: 'Wasp GitHub Open Issues', value: response.data.open_issues },\n ]\n\n await Promise.all(metrics.map(upsertMetric))\n\n return metrics\n}\n")),(0,o.kt)("p",null,"Wasp allows you to write a regular async JavaScript function (like the one above that gathers GitHub metrics and stores them in the DB) and have it run within the context of a job queue system, which we call an executor. You can manually submit work to be done on the server, or specify a cron schedule to have your job automatically invoked. And, best of all, as we add more job executors in the future, you can change where it runs on a single line in your .wasp file."),(0,o.kt)("h2",{id:"most-jobs-have-a-boss-our-first-job-executor-is-a-pg-boss-"},"Most jobs have a boss. Our first job executor is a... pg-boss. \ud83d\ude05"),(0,o.kt)("p",{align:"center"},(0,o.kt)("figure",null,(0,o.kt)("img",{alt:"Eeek",src:(0,s.Z)("img/jobs-eyes.gif")}),(0,o.kt)("figcaption",null,"Me trying to lay off the job-related puns. Ok, ok, I\u2019ll quit. Ahhh!"))),(0,o.kt)("p",null,"In my prior life as a Ruby on Rails developer, the decision of how to implement jobs was pretty simple. You had Active Job at your disposal, and for backends, you would use something like Sidekiq or Delayed Job. In a similarly paved path, Python developers would have likely looked first to Celery."),(0,o.kt)("p",null,"In the JavaScript world, ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/OptimalBits/bull"},"Bull")," is quite popular these days. However, we decided to use ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/timgit/pg-boss"},"pg-boss"),", as it too provides persistence, delayed jobs, and schedules (plus many other features). But critically, pg-boss uses PostgreSQL instead of Redis (like Bull) for storage and coordination, and this was important since we did not want to introduce any new infrastructure dependencies to our existing production stack."),(0,o.kt)("p",null,"But isn\u2019t a database as a queue an anti-pattern, you may ask? Well, historically I\u2019d probably say yes. However, PostgreSQL 9.5 added SKIP LOCKED, which it specifically mentions can aid in avoiding lock contention with multiple consumer queue-like workloads [",(0,o.kt)("a",{parentName:"p",href:"https://www.postgresql.org/docs/9.5/sql-select.html#SQL-FOR-UPDATE-SHARE"},"https://www.postgresql.org/docs/9.5/sql-select.html#SQL-FOR-UPDATE-SHARE"),"]. So for the low-volume background job workloads that many apps have, we feel using a database as a queue is a great compromise and starting point for many users from a benefit vs. complexity perspective."),(0,o.kt)("p",null,"However, we will also continue to expand the number of job execution runtimes we support. Let us know in ",(0,o.kt)("a",{parentName:"p",href:"https://discord.gg/rzdnErX"},"Discord")," what you\u2019d like to see next!"),(0,o.kt)("h2",{id:"real-example---updating-waspleau"},"Real Example - Updating Waspleau"),(0,o.kt)("p",null,"If you are a regular reader of this blog (thank you, you deserve a raise! \ud83d\ude0a), you may recall we created an example app of a metrics dashboard called ",(0,o.kt)("a",{parentName:"p",href:"https://wasp-lang.dev/blog/2022/01/27/waspleau"},"Waspleau")," that used workers in the background to make periodic HTTP calls for data. In that example, we didn\u2019t yet have access to recurring jobs in Wasp, so we used Bull for scheduled jobs instead. To set up our queue-related logic we had to have this huge ",(0,o.kt)("inlineCode",{parentName:"p"},"setupFn")," wiring it all up; but now, we can remove all that code and simply use jobs instead! Here is what the new DSL looks like:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-wasp",metastring:"title=main.wasp",title:"main.wasp"},'// A cron job for fetching GitHub stats\njob getGithubStats {\n executor: PgBoss,\n perform: {\n fn: import { workerFunction } from "@server/workers/github.js"\n },\n schedule: {\n cron: "*/10 * * * *"\n }\n}\n\n// A cron job to measure how long a webpage takes to load\njob calcPageLoadTime {\n executor: PgBoss,\n perform: {\n fn: import { workerFunction } from "@server/workers/loadTime.js"\n },\n schedule: {\n cron: "*/5 * * * *",\n args: {=json {\n "url": "https://wasp-lang.dev",\n "name": "wasp-lang.dev Load Time"\n } json=}\n }\n}\n')),(0,o.kt)("p",null,"And here is an example of how you can reference and invoke jobs on the server. ",(0,o.kt)("em",{parentName:"p"},"Note: We did not even need to do this step since jobs with a schedule are automatically configured to run at the desired time.")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-js",metastring:"title=src/server/serverSetup.js",title:"src/server/serverSetup.js"},"/**\n* These Jobs are automatically scheduled by Wasp.\n* However, let's kick them off on server setup to ensure we have data right away.\n*/\nimport { github } from '@wasp/jobs/getGithubStats.js'\nimport { loadTime } from '@wasp/jobs/calcPageLoadTime.js'\n\nexport default async function () {\n await github.submit()\n await loadTime.submit({\n url: \"https://wasp-lang.dev\",\n name: \"wasp-lang.dev Load Time\"\n })\n}\n")),(0,o.kt)("p",null,"And voila, it is really that simple. Wasp takes care of setting up pg-boss and hooking up all your job callbacks, leaving you to focus on what matters- your own code. Here is a visual of what is happening behind the scenes:"),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Architecture",src:a(37149).Z,width:"2626",height:"1452"})),(0,o.kt)("p",null,"For those interested, check out the ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/wasp-lang/wasp/commit/1721371fc73f4485ca0046aafea2ee3fc0be41cf#diff-e158328e137176b595ad01641ba68faf82dbb88ccc5be3597009bb576fcd6505"},"full diff here")," and weep with joy for all those boilerplate lines of code we fired! We were also able to ax Redis from our infrastructure!"),(0,o.kt)("h2",{id:"looks-neat-whats-next"},"Looks neat! What\u2019s next?"),(0,o.kt)("p",null,"First off, please check out our docs for ",(0,o.kt)("a",{parentName:"p",href:"/docs/advanced/jobs"},"Jobs"),". There, you will find all the info you need to start using them. Next, if you want to see the code for this example in full, you can find it here: ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/wasp-lang/wasp/tree/release/examples/waspleau"},"https://github.com/wasp-lang/wasp/tree/release/examples/waspleau")),(0,o.kt)("p",null,"In the future, we plan to add more job executors, including support for polyglot workers (imagine running your Python ML function from Wasp!). We are also open to any other ideas on how jobs can become more useful to you (like client-side access to server-side jobs, or client-side jobs using similar abstractions?). Let us know what you think!"),(0,o.kt)("hr",null),(0,o.kt)("small",null,"Special thanks to Tim Jones for his hard work building an amazing OSS library, ",(0,o.kt)("a",{href:"https://github.com/timgit/pg-boss",target:"_blank"},"pg-boss"),", and for reviewing this post. Please consider supporting that project if it solves your needs!"))}g.isMDXComponent=!0},70589:(e,t,a)=>{a.d(t,{ZP:()=>i});var n=a(87462),o=(a(67294),a(3905));const s={toc:[]},r="wrapper";function i(e){let{components:t,...a}=e;return(0,o.kt)(r,(0,n.Z)({},s,a,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,(0,o.kt)("em",{parentName:"p"},"Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.")))}i.isMDXComponent=!0},37149:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/jobs-arch-3ebc08ebc717194dfac7e67fca5b8a7d.png"}}]); \ No newline at end of file diff --git a/assets/js/0608e6cc.e9a62bd2.js b/assets/js/0608e6cc.a0846a88.js similarity index 97% rename from assets/js/0608e6cc.e9a62bd2.js rename to assets/js/0608e6cc.a0846a88.js index 3093f4552a..1f975420b7 100644 --- a/assets/js/0608e6cc.e9a62bd2.js +++ b/assets/js/0608e6cc.a0846a88.js @@ -1 +1 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[7434],{3905:(e,t,a)=>{a.d(t,{Zo:()=>p,kt:()=>f});var r=a(67294);function n(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function o(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,r)}return a}function s(e){for(var t=1;t=0||(n[a]=e[a]);return n}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(n[a]=e[a])}return n}var l=r.createContext({}),c=function(e){var t=r.useContext(l),a=t;return e&&(a="function"==typeof e?e(t):s(s({},t),e)),a},p=function(e){var t=c(e.components);return r.createElement(l.Provider,{value:t},e.children)},m="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},g=r.forwardRef((function(e,t){var a=e.components,n=e.mdxType,o=e.originalType,l=e.parentName,p=i(e,["components","mdxType","originalType","parentName"]),m=c(a),g=n,f=m["".concat(l,".").concat(g)]||m[g]||u[g]||o;return a?r.createElement(f,s(s({ref:t},p),{},{components:a})):r.createElement(f,s({ref:t},p))}));function f(e,t){var a=arguments,n=t&&t.mdxType;if("string"==typeof e||n){var o=a.length,s=new Array(o);s[0]=g;var i={};for(var l in t)hasOwnProperty.call(t,l)&&(i[l]=t[l]);i.originalType=e,i[m]="string"==typeof e?e:n,s[1]=i;for(var c=2;c{a.d(t,{Z:()=>o});var r=a(67294),n=a(44996);const o=e=>r.createElement("div",null,r.createElement("p",{align:"center"},r.createElement("figure",null,r.createElement("img",{style:{width:e.width},alt:e.alt,src:(0,n.Z)(e.source)}),r.createElement("figcaption",{class:"image-caption",style:{fontStyle:"italic",opacity:.6,fontSize:"0.9rem"}},e.caption))))},92908:(e,t,a)=>{a.d(t,{Z:()=>s});var r=a(67294),n=a(39960);a(44996);const o=()=>r.createElement("span",{className:"in-blog-cta--divider"}," \u2192 "),s=()=>r.createElement("p",{className:"in-blog-cta-link-container"},r.createElement(n.Z,{className:"in-blog-cta--link",to:"https://e44cy1h4s0q.typeform.com/to/ycUzQa5A"},"We are in Beta (try it out)!"),r.createElement(o,null),r.createElement(n.Z,{className:"in-blog-cta--link",to:"https://discord.gg/rzdnErX"},"Join our community"),r.createElement(o,null),r.createElement(n.Z,{className:"in-blog-cta--link",to:"https://wasp-lang.notion.site/Founding-Engineer-at-Wasp-402274568afa4d7eb7f428f8fa2c0816"},"Work with us"))},21145:(e,t,a)=>{a.r(t),a.d(t,{assets:()=>l,contentTitle:()=>s,default:()=>u,frontMatter:()=>o,metadata:()=>i,toc:()=>c});var r=a(87462),n=(a(67294),a(3905));a(39960),a(44996),a(92908),a(70589),a(38610);const o={title:"Amicus: See how Erlis built a SaaS for legal teams with Wasp and got first paying customers!",authors:["matijasos"],image:"/img/amicus-usecase/amicus-hero-shot.png",tags:["webdev","wasp","startups","github"]},s=void 0,i={permalink:"/blog/2022/11/26/erlis-amicus-usecase",editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/blog/2022-11-26-erlis-amicus-usecase.md",source:"@site/blog/2022-11-26-erlis-amicus-usecase.md",title:"Amicus: See how Erlis built a SaaS for legal teams with Wasp and got first paying customers!",description:"amicus hero shot",date:"2022-11-26T00:00:00.000Z",formattedDate:"November 26, 2022",tags:[{label:"webdev",permalink:"/blog/tags/webdev"},{label:"wasp",permalink:"/blog/tags/wasp"},{label:"startups",permalink:"/blog/tags/startups"},{label:"github",permalink:"/blog/tags/github"}],readingTime:4.21,hasTruncateMarker:!0,authors:[{name:"Matija Sosic",title:"Co-founder & CEO @ Wasp",url:"https://github.com/matijasos",email:"matija@wasp-lang.dev",imageURL:"https://github.com/matijasos.png",key:"matijasos"}],frontMatter:{title:"Amicus: See how Erlis built a SaaS for legal teams with Wasp and got first paying customers!",authors:["matijasos"],image:"/img/amicus-usecase/amicus-hero-shot.png",tags:["webdev","wasp","startups","github"]},prevItem:{title:"Why we chose Prisma as a database layer for Wasp",permalink:"/blog/2022/11/28/why-we-chose-prisma"},nextItem:{title:"How Michael Curry chose Wasp to build Grabbit: an internal tool for managing dev resources at StudentBeans",permalink:"/blog/2022/11/26/michael-curry-usecase"}},l={authorsImageUrls:[void 0]},c=[],p={toc:c},m="wrapper";function u(e){let{components:t,...o}=e;return(0,n.kt)(m,(0,r.Z)({},p,o,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("p",null,(0,n.kt)("img",{alt:"amicus hero shot",src:a(37678).Z,width:"1920",height:"1705"})),(0,n.kt)("p",null,(0,n.kt)("a",{parentName:"p",href:"https://github.com/ErlisK"},"Erlis Kllogjri")," is an engineer based in San Francisco with broad experience ranging from mechanical engineering and C/C++ microcontroller programming to Python and web app development. In his free time, Erlis enjoys working on side projects, which is also how ",(0,n.kt)("a",{parentName:"p",href:"https://www.amicus.work/"},"Amicus")," started out."),(0,n.kt)("p",null,(0,n.kt)("a",{parentName:"p",href:"https://www.amicus.work/"},"Amicus"),' is a SaaS for legal teams - think about it as "Asana for lawyers", but with features and workflows tailored to the domain of law.'),(0,n.kt)("p",null,"Read on to learn how long it took Erlis to develop the first version of his SaaS with Wasp, how he got his first paying customers, and what features he plans to add next!"))}u.isMDXComponent=!0},70589:(e,t,a)=>{a.d(t,{ZP:()=>i});var r=a(87462),n=(a(67294),a(3905));const o={toc:[]},s="wrapper";function i(e){let{components:t,...a}=e;return(0,n.kt)(s,(0,r.Z)({},o,a,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("p",null,(0,n.kt)("em",{parentName:"p"},"Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.")))}i.isMDXComponent=!0},37678:(e,t,a)=>{a.d(t,{Z:()=>r});const r=a.p+"assets/images/amicus-hero-shot-5fa944706f38333bf0f22a6784b7fd2b.png"}}]); \ No newline at end of file +"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[7434],{3905:(e,t,a)=>{a.d(t,{Zo:()=>p,kt:()=>f});var r=a(67294);function n(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function o(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,r)}return a}function s(e){for(var t=1;t=0||(n[a]=e[a]);return n}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(n[a]=e[a])}return n}var l=r.createContext({}),c=function(e){var t=r.useContext(l),a=t;return e&&(a="function"==typeof e?e(t):s(s({},t),e)),a},p=function(e){var t=c(e.components);return r.createElement(l.Provider,{value:t},e.children)},m="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},g=r.forwardRef((function(e,t){var a=e.components,n=e.mdxType,o=e.originalType,l=e.parentName,p=i(e,["components","mdxType","originalType","parentName"]),m=c(a),g=n,f=m["".concat(l,".").concat(g)]||m[g]||u[g]||o;return a?r.createElement(f,s(s({ref:t},p),{},{components:a})):r.createElement(f,s({ref:t},p))}));function f(e,t){var a=arguments,n=t&&t.mdxType;if("string"==typeof e||n){var o=a.length,s=new Array(o);s[0]=g;var i={};for(var l in t)hasOwnProperty.call(t,l)&&(i[l]=t[l]);i.originalType=e,i[m]="string"==typeof e?e:n,s[1]=i;for(var c=2;c{a.d(t,{Z:()=>o});var r=a(67294),n=a(44996);const o=e=>r.createElement("div",null,r.createElement("p",{align:"center"},r.createElement("figure",null,r.createElement("img",{style:{width:e.width},alt:e.alt,src:(0,n.Z)(e.source)}),r.createElement("figcaption",{class:"image-caption",style:{fontStyle:"italic",opacity:.6,fontSize:"0.9rem"}},e.caption))))},92908:(e,t,a)=>{a.d(t,{Z:()=>s});var r=a(67294),n=a(39960);a(44996);const o=()=>r.createElement("span",{className:"in-blog-cta--divider"}," \u2192 "),s=()=>r.createElement("p",{className:"in-blog-cta-link-container"},r.createElement(n.Z,{className:"in-blog-cta--link",to:"https://e44cy1h4s0q.typeform.com/to/ycUzQa5A"},"We are in Beta (try it out)!"),r.createElement(o,null),r.createElement(n.Z,{className:"in-blog-cta--link",to:"https://discord.gg/rzdnErX"},"Join our community"),r.createElement(o,null),r.createElement(n.Z,{className:"in-blog-cta--link",to:"https://wasp-lang.notion.site/Founding-Engineer-at-Wasp-402274568afa4d7eb7f428f8fa2c0816"},"Work with us"))},21145:(e,t,a)=>{a.r(t),a.d(t,{assets:()=>l,contentTitle:()=>s,default:()=>u,frontMatter:()=>o,metadata:()=>i,toc:()=>c});var r=a(87462),n=(a(67294),a(3905));a(39960),a(44996),a(92908),a(70589),a(38610);const o={title:"Amicus: See how Erlis built a SaaS for legal teams with Wasp and got first paying customers!",authors:["matijasos"],image:"/img/amicus-usecase/amicus-hero-shot.png",tags:["webdev","wasp","startups","github"]},s=void 0,i={permalink:"/blog/2022/11/26/erlis-amicus-usecase",editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/blog/2022-11-26-erlis-amicus-usecase.md",source:"@site/blog/2022-11-26-erlis-amicus-usecase.md",title:"Amicus: See how Erlis built a SaaS for legal teams with Wasp and got first paying customers!",description:"amicus hero shot",date:"2022-11-26T00:00:00.000Z",formattedDate:"November 26, 2022",tags:[{label:"webdev",permalink:"/blog/tags/webdev"},{label:"wasp",permalink:"/blog/tags/wasp"},{label:"startups",permalink:"/blog/tags/startups"},{label:"github",permalink:"/blog/tags/github"}],readingTime:4.21,hasTruncateMarker:!0,authors:[{name:"Matija Sosic",title:"Co-founder & CEO @ Wasp",url:"https://github.com/matijasos",email:"matija@wasp-lang.dev",imageURL:"https://github.com/matijasos.png",key:"matijasos"}],frontMatter:{title:"Amicus: See how Erlis built a SaaS for legal teams with Wasp and got first paying customers!",authors:["matijasos"],image:"/img/amicus-usecase/amicus-hero-shot.png",tags:["webdev","wasp","startups","github"]},prevItem:{title:"Why we chose Prisma as a database layer for Wasp",permalink:"/blog/2022/11/28/why-we-chose-prisma"},nextItem:{title:"How Michael Curry chose Wasp to build Grabbit: an internal tool for managing dev resources at StudentBeans",permalink:"/blog/2022/11/26/michael-curry-usecase"}},l={authorsImageUrls:[void 0]},c=[],p={toc:c},m="wrapper";function u(e){let{components:t,...o}=e;return(0,n.kt)(m,(0,r.Z)({},p,o,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("p",null,(0,n.kt)("img",{alt:"amicus hero shot",src:a(62418).Z,width:"1920",height:"1705"})),(0,n.kt)("p",null,(0,n.kt)("a",{parentName:"p",href:"https://github.com/ErlisK"},"Erlis Kllogjri")," is an engineer based in San Francisco with broad experience ranging from mechanical engineering and C/C++ microcontroller programming to Python and web app development. In his free time, Erlis enjoys working on side projects, which is also how ",(0,n.kt)("a",{parentName:"p",href:"https://www.amicus.work/"},"Amicus")," started out."),(0,n.kt)("p",null,(0,n.kt)("a",{parentName:"p",href:"https://www.amicus.work/"},"Amicus"),' is a SaaS for legal teams - think about it as "Asana for lawyers", but with features and workflows tailored to the domain of law.'),(0,n.kt)("p",null,"Read on to learn how long it took Erlis to develop the first version of his SaaS with Wasp, how he got his first paying customers, and what features he plans to add next!"))}u.isMDXComponent=!0},70589:(e,t,a)=>{a.d(t,{ZP:()=>i});var r=a(87462),n=(a(67294),a(3905));const o={toc:[]},s="wrapper";function i(e){let{components:t,...a}=e;return(0,n.kt)(s,(0,r.Z)({},o,a,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("p",null,(0,n.kt)("em",{parentName:"p"},"Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.")))}i.isMDXComponent=!0},62418:(e,t,a)=>{a.d(t,{Z:()=>r});const r=a.p+"assets/images/amicus-hero-shot-5fa944706f38333bf0f22a6784b7fd2b.png"}}]); \ No newline at end of file diff --git a/assets/js/0b33eecc.c86b23a8.js b/assets/js/0b33eecc.c86b23a8.js deleted file mode 100644 index 408fae93c4..0000000000 --- a/assets/js/0b33eecc.c86b23a8.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[934],{7085:e=>{e.exports=JSON.parse('{"name":"docusaurus-theme-search-algolia","id":"default"}')}}]); \ No newline at end of file diff --git a/assets/js/0c3100e0.d26422f6.js b/assets/js/0c3100e0.5cf35666.js similarity index 98% rename from assets/js/0c3100e0.d26422f6.js rename to assets/js/0c3100e0.5cf35666.js index 6abe2076ad..db009cb7fb 100644 --- a/assets/js/0c3100e0.d26422f6.js +++ b/assets/js/0c3100e0.5cf35666.js @@ -1 +1 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[5962],{3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>m});var r=n(67294);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function l(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var s=r.createContext({}),u=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},c=function(e){var t=u(e.components);return r.createElement(s.Provider,{value:t},e.children)},p="mdxType",d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},v=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,s=e.parentName,c=i(e,["components","mdxType","originalType","parentName"]),p=u(n),v=a,m=p["".concat(s,".").concat(v)]||p[v]||d[v]||o;return n?r.createElement(m,l(l({ref:t},c),{},{components:n})):r.createElement(m,l({ref:t},c))}));function m(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,l=new Array(o);l[0]=v;var i={};for(var s in t)hasOwnProperty.call(t,s)&&(i[s]=t[s]);i.originalType=e,i[p]="string"==typeof e?e:a,l[1]=i;for(var u=2;u{n.d(t,{Z:()=>l});var r=n(67294),a=n(86010);const o={tabItem:"tabItem_Ymn6"};function l(e){let{children:t,hidden:n,className:l}=e;return r.createElement("div",{role:"tabpanel",className:(0,a.Z)(o.tabItem,l),hidden:n},t)}},74866:(e,t,n)=>{n.d(t,{Z:()=>E});var r=n(87462),a=n(67294),o=n(86010),l=n(12466),i=n(16550),s=n(91980),u=n(67392),c=n(50012);function p(e){return function(e){return a.Children.map(e,(e=>{if(!e||(0,a.isValidElement)(e)&&function(e){const{props:t}=e;return!!t&&"object"==typeof t&&"value"in t}(e))return e;throw new Error(`Docusaurus error: Bad child <${"string"==typeof e.type?e.type:e.type.name}>: all children of the component should be , and every should have a unique "value" prop.`)}))?.filter(Boolean)??[]}(e).map((e=>{let{props:{value:t,label:n,attributes:r,default:a}}=e;return{value:t,label:n,attributes:r,default:a}}))}function d(e){const{values:t,children:n}=e;return(0,a.useMemo)((()=>{const e=t??p(n);return function(e){const t=(0,u.l)(e,((e,t)=>e.value===t.value));if(t.length>0)throw new Error(`Docusaurus error: Duplicate values "${t.map((e=>e.value)).join(", ")}" found in . Every value needs to be unique.`)}(e),e}),[t,n])}function v(e){let{value:t,tabValues:n}=e;return n.some((e=>e.value===t))}function m(e){let{queryString:t=!1,groupId:n}=e;const r=(0,i.k6)(),o=function(e){let{queryString:t=!1,groupId:n}=e;if("string"==typeof t)return t;if(!1===t)return null;if(!0===t&&!n)throw new Error('Docusaurus error: The component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".');return n??null}({queryString:t,groupId:n});return[(0,s._X)(o),(0,a.useCallback)((e=>{if(!o)return;const t=new URLSearchParams(r.location.search);t.set(o,e),r.replace({...r.location,search:t.toString()})}),[o,r])]}function h(e){const{defaultValue:t,queryString:n=!1,groupId:r}=e,o=d(e),[l,i]=(0,a.useState)((()=>function(e){let{defaultValue:t,tabValues:n}=e;if(0===n.length)throw new Error("Docusaurus error: the component requires at least one children component");if(t){if(!v({value:t,tabValues:n}))throw new Error(`Docusaurus error: The has a defaultValue "${t}" but none of its children has the corresponding value. Available values are: ${n.map((e=>e.value)).join(", ")}. If you intend to show no default tab, use defaultValue={null} instead.`);return t}const r=n.find((e=>e.default))??n[0];if(!r)throw new Error("Unexpected error: 0 tabValues");return r.value}({defaultValue:t,tabValues:o}))),[s,u]=m({queryString:n,groupId:r}),[p,h]=function(e){let{groupId:t}=e;const n=function(e){return e?`docusaurus.tab.${e}`:null}(t),[r,o]=(0,c.Nk)(n);return[r,(0,a.useCallback)((e=>{n&&o.set(e)}),[n,o])]}({groupId:r}),f=(()=>{const e=s??p;return v({value:e,tabValues:o})?e:null})();(0,a.useLayoutEffect)((()=>{f&&i(f)}),[f]);return{selectedValue:l,selectValue:(0,a.useCallback)((e=>{if(!v({value:e,tabValues:o}))throw new Error(`Can't select invalid tab value=${e}`);i(e),u(e),h(e)}),[u,h,o]),tabValues:o}}var f=n(72389);const b={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};function g(e){let{className:t,block:n,selectedValue:i,selectValue:s,tabValues:u}=e;const c=[],{blockElementScrollPositionUntilNextRender:p}=(0,l.o5)(),d=e=>{const t=e.currentTarget,n=c.indexOf(t),r=u[n].value;r!==i&&(p(t),s(r))},v=e=>{let t=null;switch(e.key){case"Enter":d(e);break;case"ArrowRight":{const n=c.indexOf(e.currentTarget)+1;t=c[n]??c[0];break}case"ArrowLeft":{const n=c.indexOf(e.currentTarget)-1;t=c[n]??c[c.length-1];break}}t?.focus()};return a.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,o.Z)("tabs",{"tabs--block":n},t)},u.map((e=>{let{value:t,label:n,attributes:l}=e;return a.createElement("li",(0,r.Z)({role:"tab",tabIndex:i===t?0:-1,"aria-selected":i===t,key:t,ref:e=>c.push(e),onKeyDown:v,onClick:d},l,{className:(0,o.Z)("tabs__item",b.tabItem,l?.className,{"tabs__item--active":i===t})}),n??t)})))}function k(e){let{lazy:t,children:n,selectedValue:r}=e;const o=(Array.isArray(n)?n:[n]).filter(Boolean);if(t){const e=o.find((e=>e.props.value===r));return e?(0,a.cloneElement)(e,{className:"margin-top--md"}):null}return a.createElement("div",{className:"margin-top--md"},o.map(((e,t)=>(0,a.cloneElement)(e,{key:t,hidden:e.props.value!==r}))))}function y(e){const t=h(e);return a.createElement("div",{className:(0,o.Z)("tabs-container",b.tabList)},a.createElement(g,(0,r.Z)({},e,t)),a.createElement(k,(0,r.Z)({},e,t)))}function E(e){const t=(0,f.Z)();return a.createElement(y,(0,r.Z)({key:String(t)},e))}},46300:(e,t,n)=>{n.d(t,{Z:()=>o});var r=n(67294),a=n(50012);function o(e){let{path:t}=e;const[n]=(0,a.Nk)("docusaurus.tab.js-ts"),o=t.lastIndexOf("{"),l=t.slice(o+1,t.length-1),[i,s]=l.split(","),u=t.slice(0,o);return r.createElement("code",null,u+("js"===n?i:s))}},28117:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>s,default:()=>m,frontMatter:()=>i,metadata:()=>u,toc:()=>p});var r=n(87462),a=(n(67294),n(3905)),o=(n(46300),n(85162)),l=n(74866);const i={title:"Env Variables"},s=void 0,u={unversionedId:"project/env-vars",id:"version-0.12.0/project/env-vars",title:"Env Variables",description:"Environment variables are used to configure projects based on the context in which they run. This allows them to exhibit different behaviors in different environments, such as development, staging, or production.",source:"@site/versioned_docs/version-0.12.0/project/env-vars.md",sourceDirName:"project",slug:"/project/env-vars",permalink:"/docs/0.12.0/project/env-vars",draft:!1,editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/versioned_docs/version-0.12.0/project/env-vars.md",tags:[],version:"0.12.0",frontMatter:{title:"Env Variables"},sidebar:"docs",previous:{title:"Static Asset Handling",permalink:"/docs/0.12.0/project/static-assets"},next:{title:"Testing",permalink:"/docs/0.12.0/project/testing"}},c={},p=[{value:"Client Env Vars",id:"client-env-vars",level:2},{value:"Server Env Vars",id:"server-env-vars",level:2},{value:"Defining Env Vars in Development",id:"defining-env-vars-in-development",level:2},{value:"1. Using .env (dotenv) Files",id:"1-using-env-dotenv-files",level:3},{value:"2. Using Shell",id:"2-using-shell",level:3},{value:"Defining Env Vars in Production",id:"defining-env-vars-in-production",level:2},{value:"Client Env Vars",id:"client-env-vars-1",level:3},{value:"Server Env Vars",id:"server-env-vars-1",level:3}],d={toc:p},v="wrapper";function m(e){let{components:t,...i}=e;return(0,a.kt)(v,(0,r.Z)({},d,i,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,(0,a.kt)("strong",{parentName:"p"},"Environment variables")," are used to configure projects based on the context in which they run. This allows them to exhibit different behaviors in different environments, such as development, staging, or production."),(0,a.kt)("p",null,"For instance, ",(0,a.kt)("em",{parentName:"p"},"during development"),", you may want your project to connect to a local development database running on your machine, but ",(0,a.kt)("em",{parentName:"p"},"in production"),", you may prefer it to connect to the production database. Similarly, in development, you may want to use a test Stripe account, while in production, your app should use a real Stripe account."),(0,a.kt)("p",null,"While some env vars are required by Wasp, such as the database connection or secrets for social auth, you can also define your env vars for any other useful purposes."),(0,a.kt)("p",null,"In Wasp, you can use environment variables in both the client and the server code."),(0,a.kt)("h2",{id:"client-env-vars"},"Client Env Vars"),(0,a.kt)("p",null,"Client environment variables are embedded into the client code during the build and shipping process, making them public and readable by anyone. Therefore, you should ",(0,a.kt)("strong",{parentName:"p"},"never store secrets in them")," (such as secret API keys)."),(0,a.kt)("p",null,"To enable Wasp to pick them up, client environment variables must be prefixed with ",(0,a.kt)("inlineCode",{parentName:"p"},"REACT_APP_"),", for example: ",(0,a.kt)("inlineCode",{parentName:"p"},"REACT_APP_SOME_VAR_NAME=..."),"."),(0,a.kt)("p",null,"You can read them from the client code like this:"),(0,a.kt)(l.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,a.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="src/App.js"',title:'"src/App.js"'},"console.log(import.meta.env.REACT_APP_SOME_VAR_NAME)\n"))),(0,a.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/App.ts"',title:'"src/App.ts"'},"console.log(import.meta.env.REACT_APP_SOME_VAR_NAME)\n")))),(0,a.kt)("p",null,"Check below on how to define them."),(0,a.kt)("h2",{id:"server-env-vars"},"Server Env Vars"),(0,a.kt)("p",null,"In server environment variables, you can store secret values (e.g. secret API keys) since are not publicly readable. You can define them without any special prefix, such as ",(0,a.kt)("inlineCode",{parentName:"p"},"SOME_VAR_NAME=..."),"."),(0,a.kt)("p",null,"You can read them in the server code like this:"),(0,a.kt)(l.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,a.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-js"},"console.log(process.env.SOME_VAR_NAME)\n"))),(0,a.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-ts"},"console.log(process.env.SOME_VAR_NAME)\n")))),(0,a.kt)("p",null,"Check below on how to define them."),(0,a.kt)("h2",{id:"defining-env-vars-in-development"},"Defining Env Vars in Development"),(0,a.kt)("p",null,"During development, there are two ways to provide env vars to your Wasp project:"),(0,a.kt)("ol",null,(0,a.kt)("li",{parentName:"ol"},"Using ",(0,a.kt)("inlineCode",{parentName:"li"},".env")," files. ",(0,a.kt)("strong",{parentName:"li"},"(recommended)")),(0,a.kt)("li",{parentName:"ol"},"Using shell. (useful for overrides)")),(0,a.kt)("h3",{id:"1-using-env-dotenv-files"},"1. Using .env (dotenv) Files"),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Env vars usage in development",src:n(49295).Z,width:"908",height:"672"})),(0,a.kt)("p",null,"This is the recommended method for providing env vars to your Wasp project during development."),(0,a.kt)("p",null,"In the root of your Wasp project you can create two distinct files:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},".env.server")," for env vars that will be provided to the server."),(0,a.kt)("p",{parentName:"li"},"Variables are defined in these files in the form of ",(0,a.kt)("inlineCode",{parentName:"p"},"NAME=VALUE"),", for example:"),(0,a.kt)("pre",{parentName:"li"},(0,a.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title=".env.server"',title:'".env.server"'},"DATABASE_URL=postgresql://localhost:5432\nSOME_VAR_NAME=somevalue\n"))),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},".env.client")," for env vars that will be provided to the client."),(0,a.kt)("p",{parentName:"li"}," Variables are defined in these files in the form of ",(0,a.kt)("inlineCode",{parentName:"p"},"NAME=VALUE"),", for example:"),(0,a.kt)("pre",{parentName:"li"},(0,a.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title=".env.client"',title:'".env.client"'},"REACT_APP_SOME_VAR_NAME=somevalue\n")))),(0,a.kt)("p",null,"These files should not be committed to version control, and they are already ignored by default in the ",(0,a.kt)("inlineCode",{parentName:"p"},".gitignore")," file that comes with Wasp."),(0,a.kt)("h3",{id:"2-using-shell"},"2. Using Shell"),(0,a.kt)("p",null,"If you set environment variables in the shell where you run your Wasp commands (e.g., ",(0,a.kt)("inlineCode",{parentName:"p"},"wasp start"),"), Wasp will recognize them."),(0,a.kt)("p",null,"You can set environment variables in the ",(0,a.kt)("inlineCode",{parentName:"p"},".profile")," or a similar file, or by defining them at the start of a command:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-shell"},"SOME_VAR_NAME=SOMEVALUE wasp start\n")),(0,a.kt)("p",null," This is not specific to Wasp and is simply how environment variables can be set in the shell."),(0,a.kt)("p",null,"Defining environment variables in this way can be cumbersome even for a single project and even more challenging to manage if you have multiple Wasp projects. Therefore, we do not recommend this as a default method for providing environment variables to Wasp projects. However, it can be useful for occasionally ",(0,a.kt)("strong",{parentName:"p"},"overriding")," specific environment variables because environment variables set this way ",(0,a.kt)("strong",{parentName:"p"},"take precedence over those defined in ",(0,a.kt)("inlineCode",{parentName:"strong"},".env")," files"),"."),(0,a.kt)("h2",{id:"defining-env-vars-in-production"},"Defining Env Vars in Production"),(0,a.kt)("p",null,"While in development, we had the option of using ",(0,a.kt)("inlineCode",{parentName:"p"},".env")," files which made it easy to define and manage env vars. However, in production, we need to provide env vars differently."),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Env vars usage in development and production",src:n(33168).Z,width:"908",height:"672"})),(0,a.kt)("h3",{id:"client-env-vars-1"},"Client Env Vars"),(0,a.kt)("p",null,"Client env vars are embedded into the client code during the build and shipping process, making them public and readable by anyone. Therefore, you should ",(0,a.kt)("strong",{parentName:"p"},"never store secrets in them")," (such as secret API keys)."),(0,a.kt)("p",null,"You should provide them to the build command, for example:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-shell"},"REACT_APP_SOME_VAR_NAME=somevalue npm run build\n")),(0,a.kt)("admonition",{title:"How it works",type:"info"},(0,a.kt)("p",{parentName:"admonition"},"What happens behind the scenes is that Wasp will replace all occurrences of ",(0,a.kt)("inlineCode",{parentName:"p"},"import.meta.env.REACT_APP_SOME_VAR_NAME")," with the value you provided. This is done during the build process, so the value is embedded into the client code."),(0,a.kt)("p",{parentName:"admonition"},"Read more about it in Vite's ",(0,a.kt)("a",{parentName:"p",href:"https://vitejs.dev/guide/env-and-mode.html#production-replacement"},"docs"),".")),(0,a.kt)("h3",{id:"server-env-vars-1"},"Server Env Vars"),(0,a.kt)("p",null,"The way you provide env vars to your Wasp project in production depends on where you deploy it. For example, if you deploy your project to ",(0,a.kt)("a",{parentName:"p",href:"https://fly.io"},"Fly"),", you can define them using the ",(0,a.kt)("inlineCode",{parentName:"p"},"flyctl")," CLI tool:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-shell"},"flyctl secrets set SOME_VAR_NAME=somevalue\n")),(0,a.kt)("p",null,"You can read a lot more details in the ",(0,a.kt)("a",{parentName:"p",href:"../advanced/deployment/manually"},"deployment section")," of the docs. We go into detail on how to define env vars for each deployment option."))}m.isMDXComponent=!0},49295:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/prod_dev_fade-e4097e7d9b64c62ca95bfde692e5115d.svg"},33168:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/prod_dev_fade_2-d0ff1e438a29011a68bcf630a9470254.svg"}}]); \ No newline at end of file +"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[5962],{3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>m});var r=n(67294);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function l(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var s=r.createContext({}),u=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},c=function(e){var t=u(e.components);return r.createElement(s.Provider,{value:t},e.children)},p="mdxType",d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},v=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,s=e.parentName,c=i(e,["components","mdxType","originalType","parentName"]),p=u(n),v=a,m=p["".concat(s,".").concat(v)]||p[v]||d[v]||o;return n?r.createElement(m,l(l({ref:t},c),{},{components:n})):r.createElement(m,l({ref:t},c))}));function m(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,l=new Array(o);l[0]=v;var i={};for(var s in t)hasOwnProperty.call(t,s)&&(i[s]=t[s]);i.originalType=e,i[p]="string"==typeof e?e:a,l[1]=i;for(var u=2;u{n.d(t,{Z:()=>l});var r=n(67294),a=n(86010);const o={tabItem:"tabItem_Ymn6"};function l(e){let{children:t,hidden:n,className:l}=e;return r.createElement("div",{role:"tabpanel",className:(0,a.Z)(o.tabItem,l),hidden:n},t)}},74866:(e,t,n)=>{n.d(t,{Z:()=>E});var r=n(87462),a=n(67294),o=n(86010),l=n(12466),i=n(16550),s=n(91980),u=n(67392),c=n(50012);function p(e){return function(e){return a.Children.map(e,(e=>{if(!e||(0,a.isValidElement)(e)&&function(e){const{props:t}=e;return!!t&&"object"==typeof t&&"value"in t}(e))return e;throw new Error(`Docusaurus error: Bad child <${"string"==typeof e.type?e.type:e.type.name}>: all children of the component should be , and every should have a unique "value" prop.`)}))?.filter(Boolean)??[]}(e).map((e=>{let{props:{value:t,label:n,attributes:r,default:a}}=e;return{value:t,label:n,attributes:r,default:a}}))}function d(e){const{values:t,children:n}=e;return(0,a.useMemo)((()=>{const e=t??p(n);return function(e){const t=(0,u.l)(e,((e,t)=>e.value===t.value));if(t.length>0)throw new Error(`Docusaurus error: Duplicate values "${t.map((e=>e.value)).join(", ")}" found in . Every value needs to be unique.`)}(e),e}),[t,n])}function v(e){let{value:t,tabValues:n}=e;return n.some((e=>e.value===t))}function m(e){let{queryString:t=!1,groupId:n}=e;const r=(0,i.k6)(),o=function(e){let{queryString:t=!1,groupId:n}=e;if("string"==typeof t)return t;if(!1===t)return null;if(!0===t&&!n)throw new Error('Docusaurus error: The component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".');return n??null}({queryString:t,groupId:n});return[(0,s._X)(o),(0,a.useCallback)((e=>{if(!o)return;const t=new URLSearchParams(r.location.search);t.set(o,e),r.replace({...r.location,search:t.toString()})}),[o,r])]}function h(e){const{defaultValue:t,queryString:n=!1,groupId:r}=e,o=d(e),[l,i]=(0,a.useState)((()=>function(e){let{defaultValue:t,tabValues:n}=e;if(0===n.length)throw new Error("Docusaurus error: the component requires at least one children component");if(t){if(!v({value:t,tabValues:n}))throw new Error(`Docusaurus error: The has a defaultValue "${t}" but none of its children has the corresponding value. Available values are: ${n.map((e=>e.value)).join(", ")}. If you intend to show no default tab, use defaultValue={null} instead.`);return t}const r=n.find((e=>e.default))??n[0];if(!r)throw new Error("Unexpected error: 0 tabValues");return r.value}({defaultValue:t,tabValues:o}))),[s,u]=m({queryString:n,groupId:r}),[p,h]=function(e){let{groupId:t}=e;const n=function(e){return e?`docusaurus.tab.${e}`:null}(t),[r,o]=(0,c.Nk)(n);return[r,(0,a.useCallback)((e=>{n&&o.set(e)}),[n,o])]}({groupId:r}),f=(()=>{const e=s??p;return v({value:e,tabValues:o})?e:null})();(0,a.useLayoutEffect)((()=>{f&&i(f)}),[f]);return{selectedValue:l,selectValue:(0,a.useCallback)((e=>{if(!v({value:e,tabValues:o}))throw new Error(`Can't select invalid tab value=${e}`);i(e),u(e),h(e)}),[u,h,o]),tabValues:o}}var f=n(72389);const b={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};function g(e){let{className:t,block:n,selectedValue:i,selectValue:s,tabValues:u}=e;const c=[],{blockElementScrollPositionUntilNextRender:p}=(0,l.o5)(),d=e=>{const t=e.currentTarget,n=c.indexOf(t),r=u[n].value;r!==i&&(p(t),s(r))},v=e=>{let t=null;switch(e.key){case"Enter":d(e);break;case"ArrowRight":{const n=c.indexOf(e.currentTarget)+1;t=c[n]??c[0];break}case"ArrowLeft":{const n=c.indexOf(e.currentTarget)-1;t=c[n]??c[c.length-1];break}}t?.focus()};return a.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,o.Z)("tabs",{"tabs--block":n},t)},u.map((e=>{let{value:t,label:n,attributes:l}=e;return a.createElement("li",(0,r.Z)({role:"tab",tabIndex:i===t?0:-1,"aria-selected":i===t,key:t,ref:e=>c.push(e),onKeyDown:v,onClick:d},l,{className:(0,o.Z)("tabs__item",b.tabItem,l?.className,{"tabs__item--active":i===t})}),n??t)})))}function k(e){let{lazy:t,children:n,selectedValue:r}=e;const o=(Array.isArray(n)?n:[n]).filter(Boolean);if(t){const e=o.find((e=>e.props.value===r));return e?(0,a.cloneElement)(e,{className:"margin-top--md"}):null}return a.createElement("div",{className:"margin-top--md"},o.map(((e,t)=>(0,a.cloneElement)(e,{key:t,hidden:e.props.value!==r}))))}function y(e){const t=h(e);return a.createElement("div",{className:(0,o.Z)("tabs-container",b.tabList)},a.createElement(g,(0,r.Z)({},e,t)),a.createElement(k,(0,r.Z)({},e,t)))}function E(e){const t=(0,f.Z)();return a.createElement(y,(0,r.Z)({key:String(t)},e))}},46300:(e,t,n)=>{n.d(t,{Z:()=>o});var r=n(67294),a=n(50012);function o(e){let{path:t}=e;const[n]=(0,a.Nk)("docusaurus.tab.js-ts"),o=t.lastIndexOf("{"),l=t.slice(o+1,t.length-1),[i,s]=l.split(","),u=t.slice(0,o);return r.createElement("code",null,u+("js"===n?i:s))}},28117:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>s,default:()=>m,frontMatter:()=>i,metadata:()=>u,toc:()=>p});var r=n(87462),a=(n(67294),n(3905)),o=(n(46300),n(85162)),l=n(74866);const i={title:"Env Variables"},s=void 0,u={unversionedId:"project/env-vars",id:"version-0.12.0/project/env-vars",title:"Env Variables",description:"Environment variables are used to configure projects based on the context in which they run. This allows them to exhibit different behaviors in different environments, such as development, staging, or production.",source:"@site/versioned_docs/version-0.12.0/project/env-vars.md",sourceDirName:"project",slug:"/project/env-vars",permalink:"/docs/0.12.0/project/env-vars",draft:!1,editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/versioned_docs/version-0.12.0/project/env-vars.md",tags:[],version:"0.12.0",frontMatter:{title:"Env Variables"},sidebar:"docs",previous:{title:"Static Asset Handling",permalink:"/docs/0.12.0/project/static-assets"},next:{title:"Testing",permalink:"/docs/0.12.0/project/testing"}},c={},p=[{value:"Client Env Vars",id:"client-env-vars",level:2},{value:"Server Env Vars",id:"server-env-vars",level:2},{value:"Defining Env Vars in Development",id:"defining-env-vars-in-development",level:2},{value:"1. Using .env (dotenv) Files",id:"1-using-env-dotenv-files",level:3},{value:"2. Using Shell",id:"2-using-shell",level:3},{value:"Defining Env Vars in Production",id:"defining-env-vars-in-production",level:2},{value:"Client Env Vars",id:"client-env-vars-1",level:3},{value:"Server Env Vars",id:"server-env-vars-1",level:3}],d={toc:p},v="wrapper";function m(e){let{components:t,...i}=e;return(0,a.kt)(v,(0,r.Z)({},d,i,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,(0,a.kt)("strong",{parentName:"p"},"Environment variables")," are used to configure projects based on the context in which they run. This allows them to exhibit different behaviors in different environments, such as development, staging, or production."),(0,a.kt)("p",null,"For instance, ",(0,a.kt)("em",{parentName:"p"},"during development"),", you may want your project to connect to a local development database running on your machine, but ",(0,a.kt)("em",{parentName:"p"},"in production"),", you may prefer it to connect to the production database. Similarly, in development, you may want to use a test Stripe account, while in production, your app should use a real Stripe account."),(0,a.kt)("p",null,"While some env vars are required by Wasp, such as the database connection or secrets for social auth, you can also define your env vars for any other useful purposes."),(0,a.kt)("p",null,"In Wasp, you can use environment variables in both the client and the server code."),(0,a.kt)("h2",{id:"client-env-vars"},"Client Env Vars"),(0,a.kt)("p",null,"Client environment variables are embedded into the client code during the build and shipping process, making them public and readable by anyone. Therefore, you should ",(0,a.kt)("strong",{parentName:"p"},"never store secrets in them")," (such as secret API keys)."),(0,a.kt)("p",null,"To enable Wasp to pick them up, client environment variables must be prefixed with ",(0,a.kt)("inlineCode",{parentName:"p"},"REACT_APP_"),", for example: ",(0,a.kt)("inlineCode",{parentName:"p"},"REACT_APP_SOME_VAR_NAME=..."),"."),(0,a.kt)("p",null,"You can read them from the client code like this:"),(0,a.kt)(l.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,a.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="src/App.js"',title:'"src/App.js"'},"console.log(import.meta.env.REACT_APP_SOME_VAR_NAME)\n"))),(0,a.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/App.ts"',title:'"src/App.ts"'},"console.log(import.meta.env.REACT_APP_SOME_VAR_NAME)\n")))),(0,a.kt)("p",null,"Check below on how to define them."),(0,a.kt)("h2",{id:"server-env-vars"},"Server Env Vars"),(0,a.kt)("p",null,"In server environment variables, you can store secret values (e.g. secret API keys) since are not publicly readable. You can define them without any special prefix, such as ",(0,a.kt)("inlineCode",{parentName:"p"},"SOME_VAR_NAME=..."),"."),(0,a.kt)("p",null,"You can read them in the server code like this:"),(0,a.kt)(l.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,a.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-js"},"console.log(process.env.SOME_VAR_NAME)\n"))),(0,a.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-ts"},"console.log(process.env.SOME_VAR_NAME)\n")))),(0,a.kt)("p",null,"Check below on how to define them."),(0,a.kt)("h2",{id:"defining-env-vars-in-development"},"Defining Env Vars in Development"),(0,a.kt)("p",null,"During development, there are two ways to provide env vars to your Wasp project:"),(0,a.kt)("ol",null,(0,a.kt)("li",{parentName:"ol"},"Using ",(0,a.kt)("inlineCode",{parentName:"li"},".env")," files. ",(0,a.kt)("strong",{parentName:"li"},"(recommended)")),(0,a.kt)("li",{parentName:"ol"},"Using shell. (useful for overrides)")),(0,a.kt)("h3",{id:"1-using-env-dotenv-files"},"1. Using .env (dotenv) Files"),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Env vars usage in development",src:n(61965).Z,width:"908",height:"672"})),(0,a.kt)("p",null,"This is the recommended method for providing env vars to your Wasp project during development."),(0,a.kt)("p",null,"In the root of your Wasp project you can create two distinct files:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},".env.server")," for env vars that will be provided to the server."),(0,a.kt)("p",{parentName:"li"},"Variables are defined in these files in the form of ",(0,a.kt)("inlineCode",{parentName:"p"},"NAME=VALUE"),", for example:"),(0,a.kt)("pre",{parentName:"li"},(0,a.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title=".env.server"',title:'".env.server"'},"DATABASE_URL=postgresql://localhost:5432\nSOME_VAR_NAME=somevalue\n"))),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},".env.client")," for env vars that will be provided to the client."),(0,a.kt)("p",{parentName:"li"}," Variables are defined in these files in the form of ",(0,a.kt)("inlineCode",{parentName:"p"},"NAME=VALUE"),", for example:"),(0,a.kt)("pre",{parentName:"li"},(0,a.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title=".env.client"',title:'".env.client"'},"REACT_APP_SOME_VAR_NAME=somevalue\n")))),(0,a.kt)("p",null,"These files should not be committed to version control, and they are already ignored by default in the ",(0,a.kt)("inlineCode",{parentName:"p"},".gitignore")," file that comes with Wasp."),(0,a.kt)("h3",{id:"2-using-shell"},"2. Using Shell"),(0,a.kt)("p",null,"If you set environment variables in the shell where you run your Wasp commands (e.g., ",(0,a.kt)("inlineCode",{parentName:"p"},"wasp start"),"), Wasp will recognize them."),(0,a.kt)("p",null,"You can set environment variables in the ",(0,a.kt)("inlineCode",{parentName:"p"},".profile")," or a similar file, or by defining them at the start of a command:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-shell"},"SOME_VAR_NAME=SOMEVALUE wasp start\n")),(0,a.kt)("p",null," This is not specific to Wasp and is simply how environment variables can be set in the shell."),(0,a.kt)("p",null,"Defining environment variables in this way can be cumbersome even for a single project and even more challenging to manage if you have multiple Wasp projects. Therefore, we do not recommend this as a default method for providing environment variables to Wasp projects. However, it can be useful for occasionally ",(0,a.kt)("strong",{parentName:"p"},"overriding")," specific environment variables because environment variables set this way ",(0,a.kt)("strong",{parentName:"p"},"take precedence over those defined in ",(0,a.kt)("inlineCode",{parentName:"strong"},".env")," files"),"."),(0,a.kt)("h2",{id:"defining-env-vars-in-production"},"Defining Env Vars in Production"),(0,a.kt)("p",null,"While in development, we had the option of using ",(0,a.kt)("inlineCode",{parentName:"p"},".env")," files which made it easy to define and manage env vars. However, in production, we need to provide env vars differently."),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Env vars usage in development and production",src:n(18098).Z,width:"908",height:"672"})),(0,a.kt)("h3",{id:"client-env-vars-1"},"Client Env Vars"),(0,a.kt)("p",null,"Client env vars are embedded into the client code during the build and shipping process, making them public and readable by anyone. Therefore, you should ",(0,a.kt)("strong",{parentName:"p"},"never store secrets in them")," (such as secret API keys)."),(0,a.kt)("p",null,"You should provide them to the build command, for example:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-shell"},"REACT_APP_SOME_VAR_NAME=somevalue npm run build\n")),(0,a.kt)("admonition",{title:"How it works",type:"info"},(0,a.kt)("p",{parentName:"admonition"},"What happens behind the scenes is that Wasp will replace all occurrences of ",(0,a.kt)("inlineCode",{parentName:"p"},"import.meta.env.REACT_APP_SOME_VAR_NAME")," with the value you provided. This is done during the build process, so the value is embedded into the client code."),(0,a.kt)("p",{parentName:"admonition"},"Read more about it in Vite's ",(0,a.kt)("a",{parentName:"p",href:"https://vitejs.dev/guide/env-and-mode.html#production-replacement"},"docs"),".")),(0,a.kt)("h3",{id:"server-env-vars-1"},"Server Env Vars"),(0,a.kt)("p",null,"The way you provide env vars to your Wasp project in production depends on where you deploy it. For example, if you deploy your project to ",(0,a.kt)("a",{parentName:"p",href:"https://fly.io"},"Fly"),", you can define them using the ",(0,a.kt)("inlineCode",{parentName:"p"},"flyctl")," CLI tool:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-shell"},"flyctl secrets set SOME_VAR_NAME=somevalue\n")),(0,a.kt)("p",null,"You can read a lot more details in the ",(0,a.kt)("a",{parentName:"p",href:"../advanced/deployment/manually"},"deployment section")," of the docs. We go into detail on how to define env vars for each deployment option."))}m.isMDXComponent=!0},61965:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/prod_dev_fade-e4097e7d9b64c62ca95bfde692e5115d.svg"},18098:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/prod_dev_fade_2-d0ff1e438a29011a68bcf630a9470254.svg"}}]); \ No newline at end of file diff --git a/assets/js/0dc22d83.8ed7302a.js b/assets/js/0dc22d83.8ed7302a.js deleted file mode 100644 index da2ba6869c..0000000000 --- a/assets/js/0dc22d83.8ed7302a.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[6055],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>h});var a=n(67294);function s(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function r(e){for(var t=1;t=0||(s[n]=e[n]);return s}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(s[n]=e[n])}return s}var l=a.createContext({}),c=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):r(r({},t),e)),n},p=function(e){var t=c(e.components);return a.createElement(l.Provider,{value:t},e.children)},u="mdxType",d={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},m=a.forwardRef((function(e,t){var n=e.components,s=e.mdxType,i=e.originalType,l=e.parentName,p=o(e,["components","mdxType","originalType","parentName"]),u=c(n),m=s,h=u["".concat(l,".").concat(m)]||u[m]||d[m]||i;return n?a.createElement(h,r(r({ref:t},p),{},{components:n})):a.createElement(h,r({ref:t},p))}));function h(e,t){var n=arguments,s=t&&t.mdxType;if("string"==typeof e||s){var i=n.length,r=new Array(i);r[0]=m;var o={};for(var l in t)hasOwnProperty.call(t,l)&&(o[l]=t[l]);o.originalType=e,o[u]="string"==typeof e?e:s,r[1]=o;for(var c=2;c{n.d(t,{Z:()=>r});var a=n(67294),s=n(39960);n(44996);const i=()=>a.createElement("span",{className:"in-blog-cta--divider"}," \u2192 "),r=()=>a.createElement("p",{className:"in-blog-cta-link-container"},a.createElement(s.Z,{className:"in-blog-cta--link",to:"https://e44cy1h4s0q.typeform.com/to/ycUzQa5A"},"We are in Beta (try it out)!"),a.createElement(i,null),a.createElement(s.Z,{className:"in-blog-cta--link",to:"https://discord.gg/rzdnErX"},"Join our community"),a.createElement(i,null),a.createElement(s.Z,{className:"in-blog-cta--link",to:"https://wasp-lang.notion.site/Founding-Engineer-at-Wasp-402274568afa4d7eb7f428f8fa2c0816"},"Work with us"))},36709:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>o,default:()=>m,frontMatter:()=>r,metadata:()=>l,toc:()=>p});var a=n(87462),s=(n(67294),n(3905)),i=n(92908);const r={title:"Building an app to find an excuse for our sloppy work",authors:["maksym36ua"],tags:["wasp"]},o=void 0,l={permalink:"/blog/2022/09/05/dev-excuses-app-tutrial",editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/blog/2022-09-05-dev-excuses-app-tutrial.md",source:"@site/blog/2022-09-05-dev-excuses-app-tutrial.md",title:"Building an app to find an excuse for our sloppy work",description:"We\u2019ll build a web app to solve every developer's most common problem \u2013 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\u2019t excuse ourselves from building it!",date:"2022-09-05T00:00:00.000Z",formattedDate:"September 5, 2022",tags:[{label:"wasp",permalink:"/blog/tags/wasp"}],readingTime:7.445,hasTruncateMarker:!0,authors:[{name:"Maksym Khamrovskyi",title:"DevRel @ Wasp",key:"maksym36ua"}],frontMatter:{title:"Building an app to find an excuse for our sloppy work",authors:["maksym36ua"],tags:["wasp"]},prevItem:{title:"How Wasp reached 1,000 stars on GitHub (detailed stats & timeline)",permalink:"/blog/2022/09/29/journey-to-1000-gh-stars"},nextItem:{title:"How to get started with Haskell in 2022 (the straightforward way)",permalink:"/blog/2022/09/02/how-to-get-started-with-haskell-in-2022"}},c={authorsImageUrls:[void 0]},p=[{value:"The requirements were unclear.",id:"the-requirements-were-unclear",level:2},{value:"There\u2019s an issue with the third party library.",id:"theres-an-issue-with-the-third-party-library",level:2},{value:"Maybe something's wrong with the environment.",id:"maybe-somethings-wrong-with-the-environment",level:2},{value:"That worked perfectly when I developed it.",id:"that-worked-perfectly-when-i-developed-it",level:2},{value:"It would have taken twice as long to build it properly.",id:"it-would-have-taken-twice-as-long-to-build-it-properly",level:2}],u={toc:p},d="wrapper";function m(e){let{components:t,...r}=e;return(0,s.kt)(d,(0,a.Z)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,s.kt)("p",null,"We\u2019ll build a web app to solve every developer's most common problem \u2013 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\u2019t excuse ourselves from building it!"),(0,s.kt)("p",null,(0,s.kt)("img",{alt:"Best excuse of all time",src:n(1065).Z,width:"413",height:"360"})),(0,s.kt)("p",null,"Best excuse of all time! ",(0,s.kt)("a",{parentName:"p",href:"https://xkcd.com/303/"},"Taken from here.")),(0,s.kt)("h2",{id:"the-requirements-were-unclear"},"The requirements were unclear."),(0,s.kt)("p",null,"We\u2019ll use Michele Gerarduzzi\u2019s ",(0,s.kt)("a",{parentName:"p",href:"https://github.com/michelegera/devexcuses-api"},"open-source project"),". It provides a simple API and a solid number of predefined excuses. A perfect fit for our needs. Let\u2019s define the requirements for the project: "),(0,s.kt)("ul",null,(0,s.kt)("li",{parentName:"ul"},"The app should be able to pull excuses data from a public API. "),(0,s.kt)("li",{parentName:"ul"},"Save the ones you liked (and your boss doesn't) to the database for future reference."),(0,s.kt)("li",{parentName:"ul"},"Building an app shouldn\u2019t take more than 15 minutes."),(0,s.kt)("li",{parentName:"ul"},"Use modern web dev technologies (NodeJS + React)")),(0,s.kt)("p",null,"As a result \u2013 we\u2019ll get a simple and fun pet project. You can find the complete codebase ",(0,s.kt)("a",{parentName:"p",href:"https://github.com/wasp-lang/wasp/tree/590a08bb14284835c9785d416980da61fe9e0db0/examples/tutorials/ItWaspsOnMyMachine"},"here"),". "),(0,s.kt)("p",null,(0,s.kt)("img",{alt:"Final result",src:n(9396).Z,width:"996",height:"568"})),(0,s.kt)("h2",{id:"theres-an-issue-with-the-third-party-library"},"There\u2019s an issue with the third party library."),(0,s.kt)("p",null,"Setting up a backbone for the project is the most frustrating part of building any application. "),(0,s.kt)("p",null,"We are installing dependencies, tying up the back-end and front-end, setting up a database, managing connection strings, and so on. Avoiding this part will save us a ton of time and effort. So let\u2019s find ourselves an excuse to skip the initial project setup."),(0,s.kt)("p",null,"Ideally \u2013 use a framework that will create a project infrastructure quickly with the best defaults so that we\u2019ll focus on the business logic. A perfect candidate is ",(0,s.kt)("a",{parentName:"p",href:"https://wasp-lang.dev/"},"Wasp"),". It\u2019s an open-source, declarative DSL for building web apps in React and Node.js with no boilerplate"),(0,s.kt)("p",null,"How it works: developer starts from a single config file that specifies the app architecture. Routes, CRUD API, auth, and so on. Then adds React/Node.js code for the specific business logic. Behind the scenes, Wasp compiler will produce the entire source code of the app - back-end, front-end, deployment template, database migrations and everything else you\u2019ve used to have in any other full-stack app. "),(0,s.kt)("p",null,(0,s.kt)("img",{alt:"Wasp architecture",src:n(48453).Z,width:"1525",height:"696"})),(0,s.kt)("p",null,"So let\u2019s jump right in."),(0,s.kt)("h2",{id:"maybe-somethings-wrong-with-the-environment"},"Maybe something's wrong with the environment."),(0,s.kt)("p",null,"Wasp intentionally works with the LTS Node.js version since it guarantees stability and active maintenance. As for now, it\u2019s Node 16 and NPM 8. If you need another Node version for some other project \u2013 there\u2019s a possibility to ",(0,s.kt)("a",{parentName:"p",href:"https://wasp-lang.dev/docs#1-requirements"},"use NVM")," to manage multiple Node versions on your computer at the same time."),(0,s.kt)("p",null,"Installing Wasp on Linux (for Mac/Windows, please ",(0,s.kt)("a",{parentName:"p",href:"https://wasp-lang.dev/docs#2-installation"},"check the docs"),"):"),(0,s.kt)("pre",null,(0,s.kt)("code",{parentName:"pre"},"curl -sSL https://get.wasp-lang.dev/installer.sh | sh\n")),(0,s.kt)("p",null,"Now let\u2019s create a new web app named ItWaspsOnMyMachine."),(0,s.kt)("pre",null,(0,s.kt)("code",{parentName:"pre"},"wasp new ItWaspsOnMyMachine\n")),(0,s.kt)("p",null,"Changing the working directory:"),(0,s.kt)("pre",null,(0,s.kt)("code",{parentName:"pre"},"cd ItWaspsOnMyMachine\n")),(0,s.kt)("p",null,"Starting the app:"),(0,s.kt)("pre",null,(0,s.kt)("code",{parentName:"pre"},"wasp start\n")),(0,s.kt)("p",null,"Now your default browser should open up with a simple predefined text message. That\u2019s it! \ud83e\udd73 We\u2019ve built and run a NodeJS + React application. And for now \u2013 the codebase consists of only two files! ",(0,s.kt)("inlineCode",{parentName:"p"},"main.wasp")," is the config file that defines the application\u2019s functionality. And ",(0,s.kt)("inlineCode",{parentName:"p"},"MainPage.js")," is the front-end."),(0,s.kt)("p",null,(0,s.kt)("img",{alt:"Initial page",src:n(53575).Z,width:"1891",height:"1043"})),(0,s.kt)("h2",{id:"that-worked-perfectly-when-i-developed-it"},"That worked perfectly when I developed it."),(0,s.kt)("p",null,(0,s.kt)("strong",{parentName:"p"},"1) Let\u2019s add some additional configuration to our ",(0,s.kt)("inlineCode",{parentName:"strong"},"main.wasp")," file. So it will look like this:")),(0,s.kt)("pre",null,(0,s.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="main.wasp | Defining Excuse entity, queries and action"',title:'"main.wasp',"|":!0,Defining:!0,Excuse:!0,"entity,":!0,queries:!0,and:!0,'action"':!0},'\n// Main declaration, defines a new web app.\napp ItWaspsOnMyMachine {\n // Wasp compiler configuration\n wasp: {\n version: "^0.6.0"\n },\n\n // Used as a browser tab title. \n title: "It Wasps On My Machine",\n\n head: [\n // Adding Tailwind to make our UI prettier\n " - - + + -
-
By Vinny
7 min read

Building and Selling a GPT Wrapper SaaS in 5 Months

Read more→
By Vinny
12 min read

Why We Don't Have a Laravel For JavaScript... Yet

Read more →

By Vinny
12 min read

How to get a Web Dev Job in 2024

Read more →

By Vinny
9 min read

The first framework that lets you visualize your React/NodeJS app's code

Read more →

By Vinny
10 min read

Open SaaS: our free, open-source SaaS starter

Read more →

By Matija Sosic
5 min read

Wasp Launch Week #5: Waspnado 🐝 🌪️

Read more →

By Matija Sosic
14 min read

On the Importance of RFCs in Programming

Read more →

By Boris Martinović
10 min read

A Guide to Windows Development with Wasp & WSL

Read more →

By Matija Sosic
5 min read

Wasp Launch Week #4: Waspolution

Read more →

By Martin Sosic
12 min read

On the Importance of Naming in Programming

Read more →

By Vinny
10 min read

Contributing to Tech Communities: How Open-Source can land you a job and get you out of the Skill Paradox

Read more →

By Vinny
31 min read

Build your own AI Meme Generator & learn how to use OpenAI's function calls

Read more →

By Vinny
9 min read

Using Product Requirement Documents to Generate Better Web Apps with AI

Read more →

By Vinny
22 min read

Build a real-time voting app with WebSockets, React & TypeScript 🔌⚡️

Read more →

By Vinny
27 min read

Smol AI 🐣 vs. Wasp AI 🐝 - Which is the Better AI Junior Developer?

Read more →

By Martin Sosic
23 min read

How we built a GPT code agent that generates full-stack web apps in React & Node.js, explained simply

Read more →

By Martin Sosic
6 min read

GPT Web App Generator - Let AI create a full-stack React & Node.js codebase based on your description 🤖🤯

Read more →

By Vinny
4 min read

Tutorial Jam #1 - Teach Others & Win Prizes!

Read more →

By Matija Sosic
2 min read

Wasp LSP 2.0 - Next-level autocompletion and IDE integration for Wasp projects!

Read more →

By Matija Sosic
4 min read

What can you build with Wasp?

Read more →

By Vinny
46 min read

Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

Read more →

By Matija Sosic
6 min read

Wasp Launch Week #3: Magic

Read more →

By Matija Sosic
6 min read

Wasp Beta - May 2023

Read more →

By Vinny
6 min read

Hackathon #2: Results & Review

Read more →

By Vinny
2 min read

Wasp Hackathon #2 - Let's "hack-a-ton"!

Read more →

By Vinny
3 min read

How I Built CoverLetterGPT - SaaS app with the PERN stack, GPT, Stripe, & Chakra UI

Read more →

By Martin Sosic
6 min read

Wasp steps up its database game with Fully Managed Dev DB & DB Seeding

Read more →

By Matija Sosic
2 min read

Wasp Auth UI: The first full-stack auth with self-updating forms!

Read more →

By Matija Sosic
7 min read

Wasp Launch Week #2

Read more →

By Matija Sosic
5 min read

New React docs pretend SPAs don't exist anymore

Read more →

By Mihovil Ilakovac
14 min read

Building a full-stack app for learning Italian: Supabase vs. Wasp

Read more →

By Vinny
4 min read

10 "Hard Truths" All Junior Developers Need to Hear

Read more →

By Matija Sosic
6 min read

Wasp Beta - February 2023

Read more →

By Vinny
6 min read

The Most Common Misconceptions Amongst Junior Developers

Read more →

By Vinny
8 min read

From Idea to Paying Customers in 1 Week: An Interview with Amicus.work

Read more →

By Vinny
3 min read

The Best Web App Framework Doesn't Exist

Read more →

By Matija Sosic
7 min read

Convincing developers to try a new web framework - the effects of launching beta

Read more →

By Matija Sosic
6 min read

Wasp Beta December 2022

Read more →

By Vinny
6 min read

Hosting Our First Hackathon: Results & Review

Read more →

By Vinny
3 min read

Watch us build a *truly* full-stack app in just 9 minutes w/ Wasp & ChatGPT 🚀 🤯

Read more →

By Martin Sosic
6 min read

Wasp Beta brings major IDE improvements

Read more →

By Filip Sodić
7 min read

Feature Release Announcement - Wasp Optimistic Updates

Read more →

By Martin Sosic
19 min read

Permissions (access control) in web apps

Read more →

By Filip Sodić
8 min read

Feature Announcement - TypeScript Support

Read more →

By Matija Sosic
3 min read

Wasp is in Beta: Auth, TypeScript, Tailwind, LSP

Read more →

By Martin Sosic
7 min read

Why we chose Prisma as a database layer for Wasp

Read more →

By Matija Sosic
5 min read

Amicus: See how Erlis built a SaaS for legal teams with Wasp and got first paying customers!

Read more →

By Matija Sosic
5 min read

How Michael Curry chose Wasp to build Grabbit: an internal tool for managing dev resources at StudentBeans

Read more →

By Matija Sosic
5 min read

Wasp Beta Launch Week announcement

Read more →

By Maksym Khamrovskyi
6 min read

How Wasp reached all-time high PR count during Hacktoberfest: tips for OSS maintainers

Read more →

By Matija Sosic
7 min read

Alpha Testing Program: post-mortem

Read more →

By Shayne Czyzewski
3 min read

Feature Announcement - Tailwind CSS support

Read more →

By Shayne Czyzewski
4 min read

Feature Announcement - New auth method (Google)

Read more →

By Matija Sosic
4 min read

Farnance: How Julian built a SaaS for farmers with Wasp and won a hackathon!

Read more →

By Matija Sosic
12 min read

How Wasp reached 1,000 stars on GitHub (detailed stats & timeline)

Read more →

By Maksym Khamrovskyi
8 min read

Building an app to find an excuse for our sloppy work

Read more →

By Martin Sosic
7 min read

How to get started with Haskell in 2022 (the straightforward way)

Read more →

By Shayne Czyzewski
8 min read

How and why I got started with Haskell

Read more →

By Vasili Shynkarenka
31 min read

How to communicate why your startup is worth joining

Read more →

By Matija Sosic
11 min read

ML code generation vs. coding by hand - what we think programming is going to look like

Read more →

By Shayne Czyzewski
7 min read

Feature Announcement - Wasp Jobs

Read more →

By Maksym Khamrovskyi
4 min read

How to win a hackathon. Brief manual.

Read more →

By Matija Sosic
6 min read

Meet the team - Filip Sodić, Founding Engineer

Read more →

By Shayne Czyzewski
5 min read

Build a metrics dashboard with background jobs in Wasp - Say hello to Waspleau!

Read more →

By Matija Sosic
4 min read

Meet the team - Shayne Czyzewski, Founding Engineer

Read more →

By Matija Sosic
10 min read

How we built a Trello clone with Wasp - Waspello!

Read more →

By Matija Sosic
8 min read

Our fundraising learnings - 250+ meetings in 98 days to the oversubscribed round

Read more →

By Matija Sosic
5 min read

Following YC, Wasp raised $1.5M Seed Round led by Lunar Ventures and HV Capital

Read more →

By Martin Sosic
9 min read

Tutorial: `forall` in Haskell

Read more →

By Martin Sosic
9 min read

How to implement a Discord bot (in NodeJS) that requires new members to introduce themselves

Read more →

By Martin Sosic
7 min read

Wasp - language for developing full-stack Javascript web apps with no boilerplate

Read more →

By Martin Sosic
4 min read

Journey to YCombinator

Read more →

By Martin Sosic
6 min read

Hello Wasp!

Read more →

- - +
+
By Matija Sosic
5 min read

Wasp Launch Week #6: The Fun Side of Web Development 🕺 🪩

Read more→
By Vinny
7 min read

Building and Selling a GPT Wrapper SaaS in 5 Months

Read more →

By Vinny
12 min read

Why We Don't Have a Laravel For JavaScript... Yet

Read more →

By Vinny
12 min read

How to get a Web Dev Job in 2024

Read more →

By Vinny
9 min read

The first framework that lets you visualize your React/NodeJS app's code

Read more →

By Vinny
10 min read

Open SaaS: our free, open-source SaaS starter

Read more →

By Matija Sosic
5 min read

Wasp Launch Week #5: Waspnado 🐝 🌪️

Read more →

By Matija Sosic
14 min read

On the Importance of RFCs in Programming

Read more →

By Boris Martinović
10 min read

A Guide to Windows Development with Wasp & WSL

Read more →

By Matija Sosic
5 min read

Wasp Launch Week #4: Waspolution

Read more →

By Martin Sosic
12 min read

On the Importance of Naming in Programming

Read more →

By Vinny
10 min read

Contributing to Tech Communities: How Open-Source can land you a job and get you out of the Skill Paradox

Read more →

By Vinny
31 min read

Build your own AI Meme Generator & learn how to use OpenAI's function calls

Read more →

By Vinny
9 min read

Using Product Requirement Documents to Generate Better Web Apps with AI

Read more →

By Vinny
22 min read

Build a real-time voting app with WebSockets, React & TypeScript 🔌⚡️

Read more →

By Vinny
27 min read

Smol AI 🐣 vs. Wasp AI 🐝 - Which is the Better AI Junior Developer?

Read more →

By Martin Sosic
23 min read

How we built a GPT code agent that generates full-stack web apps in React & Node.js, explained simply

Read more →

By Martin Sosic
6 min read

GPT Web App Generator - Let AI create a full-stack React & Node.js codebase based on your description 🤖🤯

Read more →

By Vinny
4 min read

Tutorial Jam #1 - Teach Others & Win Prizes!

Read more →

By Matija Sosic
2 min read

Wasp LSP 2.0 - Next-level autocompletion and IDE integration for Wasp projects!

Read more →

By Matija Sosic
4 min read

What can you build with Wasp?

Read more →

By Vinny
46 min read

Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

Read more →

By Matija Sosic
6 min read

Wasp Launch Week #3: Magic

Read more →

By Matija Sosic
6 min read

Wasp Beta - May 2023

Read more →

By Vinny
6 min read

Hackathon #2: Results & Review

Read more →

By Vinny
2 min read

Wasp Hackathon #2 - Let's "hack-a-ton"!

Read more →

By Vinny
3 min read

How I Built CoverLetterGPT - SaaS app with the PERN stack, GPT, Stripe, & Chakra UI

Read more →

By Martin Sosic
6 min read

Wasp steps up its database game with Fully Managed Dev DB & DB Seeding

Read more →

By Matija Sosic
2 min read

Wasp Auth UI: The first full-stack auth with self-updating forms!

Read more →

By Matija Sosic
7 min read

Wasp Launch Week #2

Read more →

By Matija Sosic
5 min read

New React docs pretend SPAs don't exist anymore

Read more →

By Mihovil Ilakovac
14 min read

Building a full-stack app for learning Italian: Supabase vs. Wasp

Read more →

By Vinny
4 min read

10 "Hard Truths" All Junior Developers Need to Hear

Read more →

By Matija Sosic
6 min read

Wasp Beta - February 2023

Read more →

By Vinny
6 min read

The Most Common Misconceptions Amongst Junior Developers

Read more →

By Vinny
8 min read

From Idea to Paying Customers in 1 Week: An Interview with Amicus.work

Read more →

By Vinny
3 min read

The Best Web App Framework Doesn't Exist

Read more →

By Matija Sosic
7 min read

Convincing developers to try a new web framework - the effects of launching beta

Read more →

By Matija Sosic
6 min read

Wasp Beta December 2022

Read more →

By Vinny
6 min read

Hosting Our First Hackathon: Results & Review

Read more →

By Vinny
3 min read

Watch us build a *truly* full-stack app in just 9 minutes w/ Wasp & ChatGPT 🚀 🤯

Read more →

By Martin Sosic
6 min read

Wasp Beta brings major IDE improvements

Read more →

By Filip Sodić
7 min read

Feature Release Announcement - Wasp Optimistic Updates

Read more →

By Martin Sosic
19 min read

Permissions (access control) in web apps

Read more →

By Filip Sodić
8 min read

Feature Announcement - TypeScript Support

Read more →

By Matija Sosic
3 min read

Wasp is in Beta: Auth, TypeScript, Tailwind, LSP

Read more →

By Martin Sosic
7 min read

Why we chose Prisma as a database layer for Wasp

Read more →

By Matija Sosic
5 min read

Amicus: See how Erlis built a SaaS for legal teams with Wasp and got first paying customers!

Read more →

By Matija Sosic
5 min read

How Michael Curry chose Wasp to build Grabbit: an internal tool for managing dev resources at StudentBeans

Read more →

By Matija Sosic
5 min read

Wasp Beta Launch Week announcement

Read more →

By Maksym Khamrovskyi
6 min read

How Wasp reached all-time high PR count during Hacktoberfest: tips for OSS maintainers

Read more →

By Matija Sosic
7 min read

Alpha Testing Program: post-mortem

Read more →

By Shayne Czyzewski
3 min read

Feature Announcement - Tailwind CSS support

Read more →

By Shayne Czyzewski
4 min read

Feature Announcement - New auth method (Google)

Read more →

By Matija Sosic
4 min read

Farnance: How Julian built a SaaS for farmers with Wasp and won a hackathon!

Read more →

By Matija Sosic
12 min read

How Wasp reached 1,000 stars on GitHub (detailed stats & timeline)

Read more →

By Maksym Khamrovskyi
8 min read

Building an app to find an excuse for our sloppy work

Read more →

By Martin Sosic
7 min read

How to get started with Haskell in 2022 (the straightforward way)

Read more →

By Shayne Czyzewski
8 min read

How and why I got started with Haskell

Read more →

By Vasili Shynkarenka
31 min read

How to communicate why your startup is worth joining

Read more →

By Matija Sosic
11 min read

ML code generation vs. coding by hand - what we think programming is going to look like

Read more →

By Shayne Czyzewski
7 min read

Feature Announcement - Wasp Jobs

Read more →

By Maksym Khamrovskyi
4 min read

How to win a hackathon. Brief manual.

Read more →

By Matija Sosic
6 min read

Meet the team - Filip Sodić, Founding Engineer

Read more →

By Shayne Czyzewski
5 min read

Build a metrics dashboard with background jobs in Wasp - Say hello to Waspleau!

Read more →

By Matija Sosic
4 min read

Meet the team - Shayne Czyzewski, Founding Engineer

Read more →

By Matija Sosic
10 min read

How we built a Trello clone with Wasp - Waspello!

Read more →

By Matija Sosic
8 min read

Our fundraising learnings - 250+ meetings in 98 days to the oversubscribed round

Read more →

By Matija Sosic
5 min read

Following YC, Wasp raised $1.5M Seed Round led by Lunar Ventures and HV Capital

Read more →

By Martin Sosic
9 min read

Tutorial: `forall` in Haskell

Read more →

By Martin Sosic
9 min read

How to implement a Discord bot (in NodeJS) that requires new members to introduce themselves

Read more →

By Martin Sosic
7 min read

Wasp - language for developing full-stack Javascript web apps with no boilerplate

Read more →

By Martin Sosic
4 min read

Journey to YCombinator

Read more →

By Martin Sosic
6 min read

Hello Wasp!

Read more →

+ + \ No newline at end of file diff --git a/blog/2019/09/01/hello-wasp.html b/blog/2019/09/01/hello-wasp.html index d98a9fe7f8..d24f0a2b9e 100644 --- a/blog/2019/09/01/hello-wasp.html +++ b/blog/2019/09/01/hello-wasp.html @@ -19,13 +19,13 @@ - - + + -
-

Hello Wasp!

· 6 min read
Martin Sosic

About a year or so ago, brother and I started discussing how awesome it would be to have a programming language that would understand what “web app” means. Such language would, on one hand, serve as an expressive specification of the web app, while on the other hand, it would take care of “boring” work for us, while we could focus on the business logic specific for our web app.

Step by step, the idea has started to take a more concrete shape, and Wasp (Web Application SPecification language) came to life! While still very early, we are writing this blog post to explain why are we building Wasp, what is the current status and what the future may hold.

More specification, less implementation​

Imagine you want to create a simple Todo web app.

You would explain it like this to your best buddy web developer: “I want to create a web app with the title ‘Todo App’ that has a single page with a list of tasks. Each task has a description and can be either marked as done or not done. The list starts as empty and tasks can be added, deleted or marked as done. I will send you designs for this. Also, I want a user to be required to register/log in.”

Now, let’s take a look at what needs to be done to implement such an app. We need to choose technologies we are going to use (frontend, backend, database, …), figure out the project file structure, set up the build toolchain, configure linting/auto-formatting/style-guide, set up tests (unit/integration, e2e), set up deployment (production, staging), set up code sharing between frontend and backend, … . Then, once everything is set up, we need to implement basic CRUD functionality (components on frontend and API on the backend), user management, probably some kind of menu on the frontend, …

We can easily see that explanation to web developer (specification) is short and concise because many details are implicit or assumed to be handled in a reasonable default way. On the other hand, implementation is complicated since it has to take care of all the details, many of them not unique for the web app we are building but common for most of the web apps. Also, if we consider the specification through time, it would look the same now and 5 years ago. On the other hand, implementation would be different, due to the new technologies that have emerged in the meantime.

So if the specification is time-resilient, short and relatively simple to describe, while implementation is complex, volatile and requires a lot of expert knowledge, how great would it be to write more of specification and less of implementation when building a web app? For that, we need more powerful languages, that will be able to express more in less code. This is where Wasp comes in.

Wasp!​

The idea behind Wasp is to take everything repetitive and common in the development of a typical web app and have Wasp take care of those parts for us. Ideally, programming in Wasp would very much look like describing the specification to the web developer, therefore writing more specification and less implementation. Wasp is the one who will keep evolving and making sure your specification is implemented in the best possible technology using the industry best practices.

To achieve that, we made Wasp as a DSL (domain-specific language) that understands common concepts of a web app like pages, routes, frontend and backend and their relationship, entities, user and roles/permissions, etc. Other parts, those that are specific for our web app (business logic), we can still write in html/css/js/…, and then plug them into Wasp, combining the power of Wasp with the flexibility of existing technologies.

What’s up?​

We are currently working on the first version of Wasp compiler, and are planning to soon have very first, MVP version ready. It will be just the first step of our vision of what Wasp could be, but the sooner we get it out there, the sooner we can start collecting feedback and further shaping Wasp together with the community.

We believe it will take significant effort to bring Wasp to the level where a big portion of developers will be able to build the whole app with Wasp without feeling restrained by missing flexibility or options, while on the other hand, we don’t want to wait too long until people can start using Wasp. Therefore, we decided to build it from start in such a way that a developer can at any moment “eject” from Wasp and continue on their own, where “ejecting” would mean that Wasp would generate the source code of web app that you can continue working on. That is why compiler for Wasp that we are building is actually a transpiler whose output is web app written with best practices, that you can at any moment take and continue from there if you feel too limited by Wasp. It is like having a senior developer guide you through writing a web app!

This poses the following question: “In which technologies will web app that Wasp transpiler produces be implemented?”. Well, while our vision is to offer multiple flavors here, so that you can choose the combination of technologies that you want to use, for a start we are going with one fixed technology stack, based on most popular technologies: React, Redux, NodeJS, and Mongo.

Moar​

One thing that we are very excited about regarding Wasp is that Wasp understands the way web app is built. So, once you describe it in Wasp, there are many things we could be able to do with it. We could automatically generate tests since we understand the requirements. We could suggest solutions on how to improve the design of the web app. Also, since Wasp should make building web apps easier, we could build solutions on top of it, for example, a visual builder that generates Wasp code, that in turn generates a web app.

We are still very early in the Wasp journey but we are very excited about the opportunities that we imagine it could bring and about the possibilities it could unlock. We hope that this blog post will inspire others to discuss this concept and that together we will create something amazing and learn a lot on the way!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Hello Wasp!

· 6 min read
Martin Sosic

About a year or so ago, brother and I started discussing how awesome it would be to have a programming language that would understand what “web app” means. Such language would, on one hand, serve as an expressive specification of the web app, while on the other hand, it would take care of “boring” work for us, while we could focus on the business logic specific for our web app.

Step by step, the idea has started to take a more concrete shape, and Wasp (Web Application SPecification language) came to life! While still very early, we are writing this blog post to explain why are we building Wasp, what is the current status and what the future may hold.

More specification, less implementation​

Imagine you want to create a simple Todo web app.

You would explain it like this to your best buddy web developer: “I want to create a web app with the title ‘Todo App’ that has a single page with a list of tasks. Each task has a description and can be either marked as done or not done. The list starts as empty and tasks can be added, deleted or marked as done. I will send you designs for this. Also, I want a user to be required to register/log in.”

Now, let’s take a look at what needs to be done to implement such an app. We need to choose technologies we are going to use (frontend, backend, database, …), figure out the project file structure, set up the build toolchain, configure linting/auto-formatting/style-guide, set up tests (unit/integration, e2e), set up deployment (production, staging), set up code sharing between frontend and backend, … . Then, once everything is set up, we need to implement basic CRUD functionality (components on frontend and API on the backend), user management, probably some kind of menu on the frontend, …

We can easily see that explanation to web developer (specification) is short and concise because many details are implicit or assumed to be handled in a reasonable default way. On the other hand, implementation is complicated since it has to take care of all the details, many of them not unique for the web app we are building but common for most of the web apps. Also, if we consider the specification through time, it would look the same now and 5 years ago. On the other hand, implementation would be different, due to the new technologies that have emerged in the meantime.

So if the specification is time-resilient, short and relatively simple to describe, while implementation is complex, volatile and requires a lot of expert knowledge, how great would it be to write more of specification and less of implementation when building a web app? For that, we need more powerful languages, that will be able to express more in less code. This is where Wasp comes in.

Wasp!​

The idea behind Wasp is to take everything repetitive and common in the development of a typical web app and have Wasp take care of those parts for us. Ideally, programming in Wasp would very much look like describing the specification to the web developer, therefore writing more specification and less implementation. Wasp is the one who will keep evolving and making sure your specification is implemented in the best possible technology using the industry best practices.

To achieve that, we made Wasp as a DSL (domain-specific language) that understands common concepts of a web app like pages, routes, frontend and backend and their relationship, entities, user and roles/permissions, etc. Other parts, those that are specific for our web app (business logic), we can still write in html/css/js/…, and then plug them into Wasp, combining the power of Wasp with the flexibility of existing technologies.

What’s up?​

We are currently working on the first version of Wasp compiler, and are planning to soon have very first, MVP version ready. It will be just the first step of our vision of what Wasp could be, but the sooner we get it out there, the sooner we can start collecting feedback and further shaping Wasp together with the community.

We believe it will take significant effort to bring Wasp to the level where a big portion of developers will be able to build the whole app with Wasp without feeling restrained by missing flexibility or options, while on the other hand, we don’t want to wait too long until people can start using Wasp. Therefore, we decided to build it from start in such a way that a developer can at any moment “eject” from Wasp and continue on their own, where “ejecting” would mean that Wasp would generate the source code of web app that you can continue working on. That is why compiler for Wasp that we are building is actually a transpiler whose output is web app written with best practices, that you can at any moment take and continue from there if you feel too limited by Wasp. It is like having a senior developer guide you through writing a web app!

This poses the following question: “In which technologies will web app that Wasp transpiler produces be implemented?”. Well, while our vision is to offer multiple flavors here, so that you can choose the combination of technologies that you want to use, for a start we are going with one fixed technology stack, based on most popular technologies: React, Redux, NodeJS, and Mongo.

Moar​

One thing that we are very excited about regarding Wasp is that Wasp understands the way web app is built. So, once you describe it in Wasp, there are many things we could be able to do with it. We could automatically generate tests since we understand the requirements. We could suggest solutions on how to improve the design of the web app. Also, since Wasp should make building web apps easier, we could build solutions on top of it, for example, a visual builder that generates Wasp code, that in turn generates a web app.

We are still very early in the Wasp journey but we are very excited about the opportunities that we imagine it could bring and about the possibilities it could unlock. We hope that this blog post will inspire others to discuss this concept and that together we will create something amazing and learn a lot on the way!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2021/02/23/journey-to-ycombinator.html b/blog/2021/02/23/journey-to-ycombinator.html index e4ccbdd6a6..84e23264b7 100644 --- a/blog/2021/02/23/journey-to-ycombinator.html +++ b/blog/2021/02/23/journey-to-ycombinator.html @@ -19,19 +19,19 @@ - - + + -
-

Journey to YCombinator

· 4 min read
Martin Sosic

Martin & Matija at YCombinator HQ

Wasp became part of Winter 2021 YCombinator batch!

Here we describe our journey and how we got in after applying for the third time.

The beginning​

About 2 years ago (start of 2019) brother and I first started thinking about the idea of a (domain specific) language that is specialized for full-stack web app development - language that removes boilerplate and makes web development simpler. +

+

Journey to YCombinator

· 4 min read
Martin Sosic

Martin & Matija at YCombinator HQ

Wasp became part of Winter 2021 YCombinator batch!

Here we describe our journey and how we got in after applying for the third time.

The beginning​

About 2 years ago (start of 2019) brother and I first started thinking about the idea of a (domain specific) language that is specialized for full-stack web app development - language that removes boilerplate and makes web development simpler. We named it Wasp (Web App SPecification).

After working on it for about a year as a side-project (researching the space, talking with potential users, building a prototype, learning), we realized it will take our full-time dedication to make something serious out of it, so we quit the current job and went all-in into Wasp, bootstrapping ourselves while working on it, to see how far we can get.

The journey to YCombinator​

Due to the nature of Wasp (open-source, web framework / language), we were aware that we will need to raise funds at some point if we want to survive. We had a startup of our own previously, and we worked in multiple startups in the past, so we already knew quite a bit about how to go about it and what to expect.

Therefore, as soon as we went full-time into it (start of 2020), we immediately applied for YCombinator (top startup accelerator in the world). Soon, we got invited to the USA (we are from Europe) for the final on-site interview!

We spent weeks preparing for the interview, polishing our pitch, vision, business plan, our understanding of our users, doing mock interviews - all for those crucial 10 minutes (yes, interview lasts only 10 minutes!). At the end we didn’t pass the final interview, however we got encouraging feedback that, although we are too early, we have potential and should try applying again when we make more progress. This made a lot of sense to us, since we had only a very basic prototype and little traction.

We decided to continue working on Wasp for some longer time and continue applying to YC and talking with other interesting accelerators/investors, and see where that gets us - if nothing else, we will learn a lot on the way :)!

Half a year later, after making progress on multiple sides, we went for a second interview (this time online due to Covid) and while we felt it was really close, we still didn’t get in - they wanted to see more traction, more proof that people want it.

Finally, by the autumn of 2020, we were in a position where we had released an early-alpha version of Wasp, managed to build an initial community (>50 people on Discord, 500 Github stars) and made it to “Product of the day” on the Product Hunt. With all that we applied for the YC for the third time and made it in!

Interesting fact is that if you applied to YC previously and got rejected, that is actually a plus when you apply the next time (it show persistence, and they can see your progress). Also, while we did spend significant time preparing for the YC interviews, all that preparation also helped us get a better understanding of our idea, what our users(developers) really need and how to properly present it, so it was worth it regardless of the result of the interviews.

What now?​

Right now (Feb 2020) we are in the middle of the YCombinator program, building community, talking with developers and developing Wasp toward beta.

It is still just the two of us and Wasp is in early stage, but with amazing community members on our side and with YC backing us up, we are not afraid to dream big!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2021/03/02/wasp-alpha.html b/blog/2021/03/02/wasp-alpha.html index d53a896bc0..23b30e7085 100644 --- a/blog/2021/03/02/wasp-alpha.html +++ b/blog/2021/03/02/wasp-alpha.html @@ -19,12 +19,12 @@ - - + + -
-

Wasp - language for developing full-stack Javascript web apps with no boilerplate

· 7 min read
Martin Sosic

Wasp logo

For the last year and a half, my twin brother and I have been working on Wasp: a new programming language for developing full-stack web apps with less code.

Wasp is a simple declarative language that makes developing web apps easy while still allowing you to use the latest technologies like React, Node.js, and Prisma.

In this post, I will share with you why we believe Wasp could be a big thing for web development, how it works, where we are right now and what is the plan for the future!

Why Wasp?​

You know how to use React, know your way around HTML/CSS/…, know how to write business logic on the backend (e.g. in Node), but when you want to build an actual web app and deploy it for others to use, you drown in all the details and extra work - responsive UI, proper error handling, security, building, deployment, authentication, managing server state on the client, managing database, different environments, ....

Iceberg of web app development

Jose Aguinaga described in a fun way the unexpected complexity of web app development in his blog post "How it feels to learn JavaScript in 2016", which still feels relevant 4 years later.

We are building Wasp because even though we are both experienced developers and have worked on multiple complex web apps in various technologies (JQuery -> Backbone -> Angular -> React, own scripts / makefile -> Grunt -> Gulp -> Webpack, PHP -> Java -> Node.js, …), we still feel building web apps is harder than it should be, due to a lot of boilerplate and repetitive work involved in the process.

The main insight for us was that while the tech stack keeps advancing rapidly, the core requirements of the apps are mostly remaining the same (auth, routing, data model CRUD, ACL, …).

That is why almost 2 years ago we started thinking about separating web app specification (what it should do) from its implementation (how it should do it).
+

+

Wasp - language for developing full-stack Javascript web apps with no boilerplate

· 7 min read
Martin Sosic

Wasp logo

For the last year and a half, my twin brother and I have been working on Wasp: a new programming language for developing full-stack web apps with less code.

Wasp is a simple declarative language that makes developing web apps easy while still allowing you to use the latest technologies like React, Node.js, and Prisma.

In this post, I will share with you why we believe Wasp could be a big thing for web development, how it works, where we are right now and what is the plan for the future!

Why Wasp?​

You know how to use React, know your way around HTML/CSS/…, know how to write business logic on the backend (e.g. in Node), but when you want to build an actual web app and deploy it for others to use, you drown in all the details and extra work - responsive UI, proper error handling, security, building, deployment, authentication, managing server state on the client, managing database, different environments, ....

Iceberg of web app development

Jose Aguinaga described in a fun way the unexpected complexity of web app development in his blog post "How it feels to learn JavaScript in 2016", which still feels relevant 4 years later.

We are building Wasp because even though we are both experienced developers and have worked on multiple complex web apps in various technologies (JQuery -> Backbone -> Angular -> React, own scripts / makefile -> Grunt -> Gulp -> Webpack, PHP -> Java -> Node.js, …), we still feel building web apps is harder than it should be, due to a lot of boilerplate and repetitive work involved in the process.

The main insight for us was that while the tech stack keeps advancing rapidly, the core requirements of the apps are mostly remaining the same (auth, routing, data model CRUD, ACL, …).

That is why almost 2 years ago we started thinking about separating web app specification (what it should do) from its implementation (how it should do it).
This led us to the idea of extracting common web app features and concepts into a special specification language (Wasp), while the implementation details are still described via a modern stack (right now React, Node.js, Prisma).

Our vision with Wasp is to create a powerful but simple language where you can describe your web app as humanly as possible. We want to make the top of that iceberg on the image above as pleasant as possible while making the bottom part much smaller.
In such language, with just a few words, you can specify pages and their routes, specify which type of authentication you want, define basic entities / data models, describe basic data flow, choose where you want to deploy, implement specific details in React/Node, and let Wasp take care of connecting it all, building it and deploying it.

Example of wasp code describing part of a simple full-stack web app.
app todoApp {
  title: "ToDo App" /* visible in tab */
}

route "/" -> page Main
page Main {
  component: import Main from "@ext/Main.js"  /* Import your React code. */
}

auth { /* full-stack auth out-of-the-box */
  userEntity: User,
  methods: {
    usernameAndPassword: {}
  }
}

entity User {=psl
  id          Int     @id @default(autoincrement())
  username    String  @unique
  password    String
psl=}

Check here for the complete example.

Why a language (DSL), aren’t frameworks solving this already?​

Frameworks (like e.g. Ruby on Rails or Meteor) are a big inspiration to us. @@ -34,7 +34,7 @@ Currently, Wasp supports only Javascript, but we plan to add Typescript soon.
Technical note: Wasp compiler is implemented in Haskell.

Wasp compilation diagram

While right now only React and Node.js are supported, we plan to support multiple other technologies in the future.

Generated code is human readable and can easily be inspected and even ejected if Wasp becomes too limiting. If not ejecting, there is no need for you to ever look at the generated code - it is generated by Wasp in the background.

Wasp is used via wasp CLI - to run wasp project in development, all you need to do is run wasp start.

Wasp CLI output

Where is Wasp now and where is it going?​

Our big vision is to move as much of the web app domain knowledge as possible into the Wasp language itself, giving Wasp more power and flexibility.

Ultimately, since Wasp would have such a deep understanding of the web app's requirements, we could generate a visual editor on top of it - allowing non-developers to participate in development alongside developers.

Also, Wasp wouldn't be tied to the specific technology but rather support multiple technologies (React/Angular/..., Node/Go/...**.

Wasp is currently in Alpha and some features are still rough or missing, there are things we haven’t solved yet and others that will probably change as we progress, but you can try it out and build and deploy web apps!

What Wasp currently supports:​

  • ✅ full-stack auth (username & password)
  • ✅ pages & routing
  • ✅ blurs the line between client & server - define your server actions and queries and call them directly in your client code (RPC)!
  • ✅ smart caching of server actions and queries (automatic cache invalidation)
  • ✅ entity (data model) definition with Prisma.io
  • ✅ ACL on frontend
  • ✅ importing NPM dependencies

What is coming:​

  • ⏳ ACL on backend
  • ⏳ one-click deployment
  • ⏳ more auth methods (Google, Linkedin, ...**
  • ⏳ tighter integration of entities with other features
  • ⏳ themes and layouts
  • ⏳ support for explicitly defined server API
  • ⏳ inline JS - the ability to mix JS code with Wasp code!
  • ⏳ Typescript support
  • ⏳ server-side rendering
  • ⏳ Visual Editor
  • ⏳ support for different languages on the backend
  • ⏳ richer wasp language with better tooling

You can check out our repo at https://github.com/wasp-lang/wasp and give it a try at https://wasp-lang.dev/docs -> we are always looking for feedback and suggestions on how to shape Wasp!

We also have a community on Discord, where we chat about Wasp-related stuff - join us to see what we are up to, share your opinions or get help with your Wasp project.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2021/04/29/discord-bot-introduction.html b/blog/2021/04/29/discord-bot-introduction.html index 4456405a16..b5b16ae8e8 100644 --- a/blog/2021/04/29/discord-bot-introduction.html +++ b/blog/2021/04/29/discord-bot-introduction.html @@ -19,12 +19,12 @@ - - + + -
-

How to implement a Discord bot (in NodeJS) that requires new members to introduce themselves

· 9 min read
Martin Sosic

Guest introducing themselves and getting full-access.
A Guest user getting access by introducing themselves in the "introductions" channel.

At Wasp, we have a Discord server for our community, where we talk with people interested in and using Wasp - Waspeteers!

In the beginning, we knew everybody in the community by their name, but as it started growing, we had a lot of people joining that never wrote anything, and the community started feeling less homey, less intimate.

This was when we decided to make it required for the new members to introduce themselves to gain access to the community. +

+

How to implement a Discord bot (in NodeJS) that requires new members to introduce themselves

· 9 min read
Martin Sosic

Guest introducing themselves and getting full-access.
A Guest user getting access by introducing themselves in the "introductions" channel.

At Wasp, we have a Discord server for our community, where we talk with people interested in and using Wasp - Waspeteers!

In the beginning, we knew everybody in the community by their name, but as it started growing, we had a lot of people joining that never wrote anything, and the community started feeling less homey, less intimate.

This was when we decided to make it required for the new members to introduce themselves to gain access to the community. We knew that with this kind of barrier we would probably lose some potential new Waspeteers, but those that would go through it would be more engaged and better integrated.

We found no other way to accomplish this automatically but to implement our own Discord bot. In this post I will describe in detail how we did it.

High-level approach​

We want the following: when a new user comes to our Discord server, they should be able to access only "public" channels, like rules, contributing, and most importantly, introductions, where they could introduce themselves.

Once they introduced themselves in the introductions channel, they would get access to the rest of the channels.

Channels user can see when Guest vs when full member.
Left: what Guest sees; Right: what Waspeteer sees.

In Discord, access control is performed via roles. There are two ways to accomplish what we need:

  1. Adding a role that grants access. When they join, they have no roles. Once they introduce themselves, they are granted a role (e.g. Member or Waspeteer) that is required to access the rest of the server.
  2. Removing a role that forbids access. When they join, they are automatically assigned a role Guest, for which we configured the non-public channels to deny access. Once they introduce themselves, the role Guest gets removed and they gain access to the rest of the server.

We decided to go with the second approach since it means we don't have to assign all the existing members with a new role. From now on, we will be talking about how to get this second approach working.

To get this going, we need to do the following:

  1. Create role Guest.
  2. Ensure that the Guest role has permissions to access only "public" channels. One convenient way to go about this is to disable "View Channels" permission for the role Guest at the level of Category, so it propagates to all the channels in it, instead of doing it for every single channel. @@ -41,7 +41,7 @@ !intro makes it easy for our bot to know when to act (in Discord, bot commands often start with !<something>).

    Let's add the needed code to bot.js:

    bot.js
    ...

    const INTRODUCTIONS_CHANNEL_ID = "<YOU_WILL_HAVE_TO_FIND_THIS_ON_DISCORD_SERVER>"

    bot.on('message', async msg => {
      if (msg.content.startsWith('!intro ')) {
        if (msg.channel.id.toString() !== INTRODUCTIONS_CHANNEL_ID) {
          const introductionsChannelName =
            msg.guild.channels.resolve(INTRODUCTIONS_CHANNEL_ID).name
          return msg.reply(
            `Please use !intro command in the ${introductionsChannelName} channel!`
          )
        }

        const introMsg = msg.content.substring('!intro '.length).trim()
        const minMsgLength = 20
        if (introMsg.length < minMsgLength) {
          return msg.reply(
            `Please write introduction at least ${minMsgLength} characters long!`
          )
        }

        return msg.reply(`Yay successful introduction!`)
      }
    })

    One thing to notice is that you will have to obtain the ID of the introductions channel and paste it in your code where I put the placeholder above. You can find out this ID by going to your Discord server in the Discord app, right-clicking on the introductions channel, and clicking on Copy ID. For this to work, you will first have to enable the "Developer Mode" (under "User Settings" > "Advanced").

    Removing the "Guest" role upon successful introduction​

    What is missing is removing the Guest role upon successful introduction, so let's do that:

    bot.js
    ...

    const INTRODUCTIONS_CHANNEL_ID = "<YOU_WILL_HAVE_TO_FIND_THIS_ON_DISCORD_SERVER>"
    const GUEST_ROLE_ID = "<YOU_WILL_HAVE_TO_FIND_THIS_ON_DISCORD_SERVER>"

    bot.on('message', async msg => {
      if (msg.content.startsWith('!intro ')) {
        if (msg.channel.id.toString() !== INTRODUCTIONS_CHANNEL_ID) {
          const introductionsChannelName =
            msg.guild.channels.resolve(INTRODUCTIONS_CHANNEL_ID).name
          return msg.reply(
          `Please use !intro command in the ${introductionsChannelName} channel!`
          )
        }

        const introMsg = msg.content.substring('!intro '.length).trim()
        const minMsgLength = 20
        if (introMsg.length < minMsgLength) {
          return msg.reply(
            `Please write introduction at least ${minMsgLength} characters long!`
          )
        }

        const member = msg.guild.member(msg.author)
        try {
          if (member.roles.cache.get(GUEST_ROLE_ID)) {
            await member.roles.remove(GUEST_ROLE_ID)
            return msg.reply(
              'Nice getting to know you! You are no longer a guest' +
              ' and have full access, welcome!'
            )
          }
        } catch (error) {
          return msg.reply(`Error: ${error}`)
        }
      }
    })

    Same as with the ID of the introductions channel, now you will also need to find out the ID of the Guest role (which you should have created at some point). You can do it by finding it in the server settings, under the list of roles, right-clicking on it, and then "Copy ID".

    This is it! You can now run the bot with

    DISCORD_BOT=<TOKEN_OF_YOUR_DISCORD_BOT> node bot.js

    and if you assign yourself a Guest role on the Discord server and then type !intro Hi this is my introduction, I am happy to be here. in the introductions channel, you should see yourself getting full access together with an appropriate message from your bot.

    Deploying the bot​

    note

    Heroku used to offer free apps under certain limits. However, as of November 28, 2022, they ended support for their free tier. https://blog.heroku.com/next-chapter

    As such, we have updated our Deployment docs with new recommendations: https://wasp-lang.dev/docs/deploying

    While there are many ways to deploy the Discord bot, I will shortly describe how we did it via Heroku.

    We created a Heroku app wasp-discord-bot and set up the "Automatic deploys" feature on Heroku to automatically deploy every push to the production branch (our bot is on Github).

    On Heroku, we set the environment variable DISCORD_BOT to the token of our bot.

    Finally, we added Procfile to our project:

    Procfile
    worker: node bot.js

    That is it! On every push to the production branch, our bot gets deployed.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2021/09/01/haskell-forall-tutorial.html b/blog/2021/09/01/haskell-forall-tutorial.html index 68ccabf063..9c487b5b68 100644 --- a/blog/2021/09/01/haskell-forall-tutorial.html +++ b/blog/2021/09/01/haskell-forall-tutorial.html @@ -19,12 +19,12 @@ - - + + -
-

Tutorial: `forall` in Haskell

· 9 min read
Martin Sosic

Find out what Haskell's forall is all about.

You might have seen forall being used in Haskell like this:

f :: forall a. [a] -> [a]
f xs = ys ++ ys
  where ys :: [a]
        ys = reverse xs

or

liftPair :: (forall x. x -> f x) -> (a, b) -> (f a, f b)

or

data Showable = forall s. (Show s) => Showable s

forall is something called "type quantifier", and it gives extra meaning to polymorphic type signatures (e.g. :: a, :: a -> b, :: a -> Int, ...).

While normaly forall plays a role of the "universal quantifier", it can also play a role of the "existential quantifier" (depends on the situation).

What does all this mean and how can forall be used in Haskell? Read on to find out!

NOTE: we assume you are comfortable with basic polymorphism in Haskell.

Quick math/logic reminder​

In mathematical logic, we have

  • universal quantifier
    • symbol: ∀x
    • interpretation: "for all", "given any"
    • example: ∀x P(x) means "for all x predicate P(x) is true".
  • existential quantifier
    • symbol: ∃x
    • interpretation: "there exists", "there is at least one", "for some"
    • example: ∃x P(x) means "there is some x for which predicate P(x) is true".

Vanilla Haskell (no extensions)​

In Haskell, all polymorphic type signatures are considered to be implicitly prefixed with forall.

Therefore, if you have

f :: a -> a
g :: a -> (a -> b) -> b

it is really the same as

f :: forall a. a -> a
g :: forall a b. a -> (a -> b) -> b

What forall here does is play the role of universal quantifier. +

+

Tutorial: `forall` in Haskell

· 9 min read
Martin Sosic

Find out what Haskell's forall is all about.

You might have seen forall being used in Haskell like this:

f :: forall a. [a] -> [a]
f xs = ys ++ ys
  where ys :: [a]
        ys = reverse xs

or

liftPair :: (forall x. x -> f x) -> (a, b) -> (f a, f b)

or

data Showable = forall s. (Show s) => Showable s

forall is something called "type quantifier", and it gives extra meaning to polymorphic type signatures (e.g. :: a, :: a -> b, :: a -> Int, ...).

While normaly forall plays a role of the "universal quantifier", it can also play a role of the "existential quantifier" (depends on the situation).

What does all this mean and how can forall be used in Haskell? Read on to find out!

NOTE: we assume you are comfortable with basic polymorphism in Haskell.

Quick math/logic reminder​

In mathematical logic, we have

  • universal quantifier
    • symbol: ∀x
    • interpretation: "for all", "given any"
    • example: ∀x P(x) means "for all x predicate P(x) is true".
  • existential quantifier
    • symbol: ∃x
    • interpretation: "there exists", "there is at least one", "for some"
    • example: ∃x P(x) means "there is some x for which predicate P(x) is true".

Vanilla Haskell (no extensions)​

In Haskell, all polymorphic type signatures are considered to be implicitly prefixed with forall.

Therefore, if you have

f :: a -> a
g :: a -> (a -> b) -> b

it is really the same as

f :: forall a. a -> a
g :: forall a b. a -> (a -> b) -> b

What forall here does is play the role of universal quantifier. For function f, it means it is saying "for all types, this function takes that type and returns the same type.". Other way to put it would be "this funtion can be called with value of any type as its first argument, and it will return the value of that same type".

Since forall is already implicit, writing it explicitly doesn't really do anything!

Not only that, but without any extensions, you can't even write forall explicitly, you will get a syntax error, since forall is not a keyword in Haskell.

So what is the purpose of forall then? Well, obviously to be used with extensions :)!

The simplest extension is ExplicitForAll, which allows you to explicitly write forall (as we did above). This is not useful on its own though, since as we said above, explicitly writing forall doesn't change anything, it was already implicitly there.

However, there are other extensions that make use of forall keyword, like: ScopedTypeVariables, RankNTypes, ExistentialQuantification. @@ -41,7 +41,7 @@ There would be no way to write its type signature without using RankNTypes.

forall and extension ExistentialQuantification​

ExistentialQuantification enables us to use forall in the type signature of data constructors.

This is useful because it enables us to define heterogeneous data types, which then allows us to store different types in a single data collection (which normally you can't do in Haskell, e.g. you can't have different types in a list).

For example, if we have

data Showable = forall s. (Show s) => Showable s

now we can do

someShowables :: [Showable]
someShowables = [Showable "Hi", Showable 5, Showable (1, 2)]

printShowables :: [Showable] -> IO ()
printShowables ss = mapM_ (\(Showable s) -> print s) ss

main :: IO ()
main = printShowables someShowables

In this example this allowed us to create a heterogeneous list, but only thing we can do with the contents of it is show them.

What is interesting is that in this case, forall plays the role of an existential quantifier (therefore the name of extension, ExistentialQuantification), unlike the role of universal quantifier it normally plays.

GADTs​

Alternative approach to ExistentialQuantification is to use the GADTs extension, like this:

{-# LANGUAGE GADTs #-}
data Showable where
  Showable :: (Show s) => s -> Showable

In this case forall is not needed, as it is implicit.

forall and extension TypeApplications​

TypeApplications does not change how forall works like the extensions above do, but it does have an interesting interaction with forall, so we will mention it here.

TypeApplications allows you to specify values of types variables in a type.

For example, you can do show (read @Int "5") to specify that "5" should be interpreted as an Int. read has type signature :: Read a => String -> a, so what @Int does is say that that a in the type signature is Int. Therefore, read @Int :: String -> Int.

How does forall come into play here?

Well, if an identifier’s type signature does not include an explicit forall, the type variable arguments appear in the left-to-right order in which the variables appear in the type. So, foo :: Monad m => a b -> m (a c) will have its type variables ordered as m, a, b, c, and type applications will happen in that order: if we have foo @Maybe @Either, @Maybe will apply to m while @Either will apply to a. However, if you want to force a different order, for example a, b, c, m, so that @Maybe in foo @Maybe @Either applies to a, you can refactor the signature as foo :: forall a b c m. Monad m => a b -> m (a c), and now order of type variables in forall will be used when doing type applications!

This will require you to enable ExplicitForAll extension, if it is not already enabled.

Conclusion

This document should give a fair idea of how forall is used and what can be done with it, but it doesn't go into much depth or cover all of the ways forall is used in Haskell.

For more in-detail explanations and further investigation, here is a couple of useful resources:

This blog post originated from the notes I wrote in wasp-lang/haskell-handbook.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2021/11/21/seed-round.html b/blog/2021/11/21/seed-round.html index 927c012ecb..67ab834ac2 100644 --- a/blog/2021/11/21/seed-round.html +++ b/blog/2021/11/21/seed-round.html @@ -19,13 +19,13 @@ - - + + -
-

Following YC, Wasp raised $1.5M Seed Round led by Lunar Ventures and HV Capital

· 5 min read
Matija Sosic

After graduating from Y Combinator's Winter 2021 Batch, we are super excited to announce that Wasp raised $1.5m in our first funding round! The round is led by Lunar Ventures and joined by HV Capital. Also see it in TechCrunch.

The best thing about it is that the majority of our investors are either experienced engineers themselves (e.g. ex-Facebook, Twitter and Airbnb) or have a strong focus on investing in deep technology and developer companies. They share the vision we have with Wasp, understand and care about the problem we are solving.

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Besides Lunar and HV Capital, we are thrilled to welcome on board:

  • 468 Capital (led by Florian Leibert, founder of Mesosphere and ex-Twitter and Airbnb eng.)
  • Charlie Songhurst
  • Tokyo Black
  • Acequia Capital
  • Abstraction Capital
  • Ben Tossell, founder of Makerpad (acq. by Zapier)
  • Muthukrishnan Ramabadran, Senior Software Engineer at Lyft
  • Yun-Fang, ex-Facebook engineer
  • Marcel P. Lima from Heller House
  • Chris Schagen, former CMO on Contentful
  • Rahul Thathoo, Sr. Eng. Manager at Square
  • Preetha Parthasarathy
  • John Kobs

Why did we raise funding?​

At its core, Wasp is an open-source project and we have full intention for it to stay that way. Open-source is one of the most powerful ways to write software and we want to make sure Wasp is freely accessible to every developer.

Wasp is a technically innovative and challenging project. Even though we are not building a new general programming language from scratch, there still exists an essential complexity of building a language and all the tooling around it. Wasp offers a lot of abstractions that are being introduced for the first time and there is no clear blueprint to follow, and this is why such an undertaking requires full-time attention and dedication. Hence, we plan on expanding the team with some amazing engineers to accelerate us on our journey.

Where are we today?​

Today, Wasp is in Alpha. That means there are many features we still have to add and many that are probably going to change. But it also means you can try it out, build a full-stack web app and see what it is all about. You can also join our community and share your feedback and experience with us - we'd be happy to hear from you!

Since we launched our Alpha several months ago, we got some amazing feedback on Product Hunt and Hacker News.

We've also grown a lot and recently passed 1,000 stars on our Github repo - thank you!

Wasp GitHub Stars

To date, over 250 projects have been created with Wasp in the last couple of months and some were even deployed to production - like Farnance that ended up being a hackathon winner! Check out their source code here.

Farnance screenshot

The team​

Martin and I have been working on Wasp for the last two years and together with our amazing contributors, who made us believe our vision is possible and made it what it is today. Having led development of several complex web apps in the past and continuously switching to the latest stack, we felt the pain and could also clearly see the patterns that we felt were mature and common enough to be worth extracting into a simpler, higher-level language.

The team
Martin and I during our first YC interview. Read here for more details on our journey to YC!

In case you couldn't tell from the photo and our identical glasses, we are twins (but not fraternal ones, and I'm a couple of minutes older, which makes me CEO :D)!

We are coming from the background of C++, algorithm competitions and applied algorithms in bioinformatics (Martin built edlib, his first OSS project - a popular sequence alignment library used by top bioinfo companies like PacBio) and did our internships in Google and Palantir. There we first encountered the modern web stack and went on to lead development of web platforms in fintech and bioinformatics space. We also had a startup previously (TalkBook), where we learned a lot about talking to users and building something that solves a problem they have.

What comes next?​

With the funding secured, we can now fully focus on developing Wasp and the ecosystem around it. We can start planning for more long-term features that we couldn't fully commit to until now, and we can expand our team to move faster and bring more great people on board with new perspectives and enable them to fully employ their knowledge and creativity without any distractions.

Our immediate focus is to bring Wasp to Beta and then 1.0 (see our high-level roadmap here), while also building a strong foundation for our open source community. We believe community is the key to the success for Wasp and we will do everything in our power to make sure everybody feels welcome and has a fun and rewarding experience both building apps and contributing to the project. If you want to shape how millions of engineers develop the web apps of tomorrow, join our community and work with us!

Thank you for reading - we can't wait to see what you will build!

We are in Beta (try it out)! → Join our community → Work with us

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Following YC, Wasp raised $1.5M Seed Round led by Lunar Ventures and HV Capital

· 5 min read
Matija Sosic

After graduating from Y Combinator's Winter 2021 Batch, we are super excited to announce that Wasp raised $1.5m in our first funding round! The round is led by Lunar Ventures and joined by HV Capital. Also see it in TechCrunch.

The best thing about it is that the majority of our investors are either experienced engineers themselves (e.g. ex-Facebook, Twitter and Airbnb) or have a strong focus on investing in deep technology and developer companies. They share the vision we have with Wasp, understand and care about the problem we are solving.

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Besides Lunar and HV Capital, we are thrilled to welcome on board:

  • 468 Capital (led by Florian Leibert, founder of Mesosphere and ex-Twitter and Airbnb eng.)
  • Charlie Songhurst
  • Tokyo Black
  • Acequia Capital
  • Abstraction Capital
  • Ben Tossell, founder of Makerpad (acq. by Zapier)
  • Muthukrishnan Ramabadran, Senior Software Engineer at Lyft
  • Yun-Fang, ex-Facebook engineer
  • Marcel P. Lima from Heller House
  • Chris Schagen, former CMO on Contentful
  • Rahul Thathoo, Sr. Eng. Manager at Square
  • Preetha Parthasarathy
  • John Kobs

Why did we raise funding?​

At its core, Wasp is an open-source project and we have full intention for it to stay that way. Open-source is one of the most powerful ways to write software and we want to make sure Wasp is freely accessible to every developer.

Wasp is a technically innovative and challenging project. Even though we are not building a new general programming language from scratch, there still exists an essential complexity of building a language and all the tooling around it. Wasp offers a lot of abstractions that are being introduced for the first time and there is no clear blueprint to follow, and this is why such an undertaking requires full-time attention and dedication. Hence, we plan on expanding the team with some amazing engineers to accelerate us on our journey.

Where are we today?​

Today, Wasp is in Alpha. That means there are many features we still have to add and many that are probably going to change. But it also means you can try it out, build a full-stack web app and see what it is all about. You can also join our community and share your feedback and experience with us - we'd be happy to hear from you!

Since we launched our Alpha several months ago, we got some amazing feedback on Product Hunt and Hacker News.

We've also grown a lot and recently passed 1,000 stars on our Github repo - thank you!

Wasp GitHub Stars

To date, over 250 projects have been created with Wasp in the last couple of months and some were even deployed to production - like Farnance that ended up being a hackathon winner! Check out their source code here.

Farnance screenshot

The team​

Martin and I have been working on Wasp for the last two years and together with our amazing contributors, who made us believe our vision is possible and made it what it is today. Having led development of several complex web apps in the past and continuously switching to the latest stack, we felt the pain and could also clearly see the patterns that we felt were mature and common enough to be worth extracting into a simpler, higher-level language.

The team
Martin and I during our first YC interview. Read here for more details on our journey to YC!

In case you couldn't tell from the photo and our identical glasses, we are twins (but not fraternal ones, and I'm a couple of minutes older, which makes me CEO :D)!

We are coming from the background of C++, algorithm competitions and applied algorithms in bioinformatics (Martin built edlib, his first OSS project - a popular sequence alignment library used by top bioinfo companies like PacBio) and did our internships in Google and Palantir. There we first encountered the modern web stack and went on to lead development of web platforms in fintech and bioinformatics space. We also had a startup previously (TalkBook), where we learned a lot about talking to users and building something that solves a problem they have.

What comes next?​

With the funding secured, we can now fully focus on developing Wasp and the ecosystem around it. We can start planning for more long-term features that we couldn't fully commit to until now, and we can expand our team to move faster and bring more great people on board with new perspectives and enable them to fully employ their knowledge and creativity without any distractions.

Our immediate focus is to bring Wasp to Beta and then 1.0 (see our high-level roadmap here), while also building a strong foundation for our open source community. We believe community is the key to the success for Wasp and we will do everything in our power to make sure everybody feels welcome and has a fun and rewarding experience both building apps and contributing to the project. If you want to shape how millions of engineers develop the web apps of tomorrow, join our community and work with us!

Thank you for reading - we can't wait to see what you will build!

We are in Beta (try it out)! → Join our community → Work with us

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2021/11/22/fundraising-learnings.html b/blog/2021/11/22/fundraising-learnings.html index 0499d92c88..257940d059 100644 --- a/blog/2021/11/22/fundraising-learnings.html +++ b/blog/2021/11/22/fundraising-learnings.html @@ -19,15 +19,15 @@ - - + + -
-

Our fundraising learnings - 250+ meetings in 98 days to the oversubscribed round

· 8 min read
Matija Sosic

Wasp fundraise chart

Wasp was part of Y Combinator’s W21 batch, which took place from January of 2021 until the end of March.

We want to share what we learned during the process!

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

At Demo Day, our product had a solid traction (200+ projects created, 1k Github stars, good ProductHunt and HackerNews feedback) but no monetisation yet, which is typical for open-source projects at this stage. Being based in the EU, we also didn't have a huge network in the Bay Area prior to the fundraise.

caution

I will try to refrain from giving "general" advice (as our fundraise is a single data point), and focus on the stats and specific things that worked for us. Keep in mind the same might not work for you - I recommend always taking advice with a pinch of salt to see what makes the most sense in your case.

As we approached our fundraise, we didn't really know what to expect. We had friends from the previous batch that raised a big round very quickly (even before Demo Day) and heard a couple of stories from a few other YC founders who were also quite successful, so we imagined it might go quickly for us too.

As you can see from the title, we had quite a journey with plenty of meetings that provided us a lot of input on how to improve our pitch, and maybe even more importantly, how to reach the right investors.

Here are our stats:

  • we spoke to 212 investors → that led to 250+ meetings
  • 98 days passed between the first and the last signed SAFE
  • 171 investor passed, 24 never responded, 17 invested

And here is how it all looked when laid out on a timeline: +

+

Our fundraising learnings - 250+ meetings in 98 days to the oversubscribed round

· 8 min read
Matija Sosic

Wasp fundraise chart

Wasp was part of Y Combinator’s W21 batch, which took place from January of 2021 until the end of March.

We want to share what we learned during the process!

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

At Demo Day, our product had a solid traction (200+ projects created, 1k Github stars, good ProductHunt and HackerNews feedback) but no monetisation yet, which is typical for open-source projects at this stage. Being based in the EU, we also didn't have a huge network in the Bay Area prior to the fundraise.

caution

I will try to refrain from giving "general" advice (as our fundraise is a single data point), and focus on the stats and specific things that worked for us. Keep in mind the same might not work for you - I recommend always taking advice with a pinch of salt to see what makes the most sense in your case.

As we approached our fundraise, we didn't really know what to expect. We had friends from the previous batch that raised a big round very quickly (even before Demo Day) and heard a couple of stories from a few other YC founders who were also quite successful, so we imagined it might go quickly for us too.

As you can see from the title, we had quite a journey with plenty of meetings that provided us a lot of input on how to improve our pitch, and maybe even more importantly, how to reach the right investors.

Here are our stats:

  • we spoke to 212 investors → that led to 250+ meetings
  • 98 days passed between the first and the last signed SAFE
  • 171 investor passed, 24 never responded, 17 invested

And here is how it all looked when laid out on a timeline: Wasp fundraise chart

Here are some of the things that worked for us:

We treated fundraising as a sales process (and stuck to it)​

Wasp fundraise funnel

This means we had a typical sales funnel - lead generation, selling (pitching) and following up:

  • Lead generation: it started with Demo Day of course, from which we got 100+ leads but none of them ended up investing (more on that below). After that we mainly relied on our YC batchmates to identify relevant investors and get the intros.
  • Pitching: we did a conversational pitch without the deck, but we had a Notion one-pager from which I would drop links during the conversation (to e.g. our traction chart, user testimonials etc.). It also worked well as investors would typically find it interesting and keep scrolling through as we talked, asking follow-up questions.
  • Following-up: we followed up once per week. I would usually "batch process" it each Wednesday. We used Streak to identify all the leads that I haven't heard from in over 7 days (there is a filter for that) and then manually emailed them.

We started with tracking everything in Google Sheets, but with the volume of leads it soon became hard to navigate them through the funnel. Then we switched to Streak (used their fundraising template, and modified it a bit) and that worked great. The most helpful thing for me was having a CRM that is integrated with gmail, that made the process much more seamless and gave us better overview of the funnel. As soon as I would receive an email I could see in which stage the investor is, and it was also super easy to add new investors straight from gmail - it saved us from the dreaded context switching and kept us focused.

Our pitch became much better after ~50 meetings​

We kept being critical of our pitch and kept a list of questions that we felt needed more work. We called it "creating narratives", e.g. why the right time for our product is now, presenting the team, or how we plan to monetise. We talked to other companies in the same space (devtools, OSS), investigated comparatives (big companies we compared ourselves too), talked to our angels who were domain experts and used all that to build a more convincing story.

I never intended to learn our pitch by heart, but after delivering it for 100s of times just that happened - both me and Martin (my brother and cofounder, who wasn't pitching but was always sitting behind me and provided feedback, especially in the beginning) knew it word by word and I realised how much more polished it sounds and how much more confident I felt compared to when we just started.

Our goal was to get to 100 no's​

After about 50 meetings (and about 20 VCs having passed on us) we started feeling a bit disheartened, as things didn't seem to go so easy as we initially expected. Then I chatted to a friend who also recently finished their fundraise and he gave me a tour of Streak - I saw their numbers and that over 150 investors passed on them! With that I realised our 20 passes were just the beginning and that instead of chasing yeses we should actually chase no's :) - they are more predictable, you'll get plenty of them and they will clearly show your progress.

We had 100+ leads from Demo Day - none of them invested​

This is probably pretty specific for our case, but it's how it went. Connecting with a startup on Demo Day is a very low-cost action for investors. Also, as many investors as there are on Demo Day, there are even more of them who aren't.

When we sorted through the connections we got, about 20% were a really good fit for us, meaning they invest in deep tech / OSS companies, have invested recently, invest in our stage etc.

We still met with pretty much all the interested leads, but we quickly realised that due to our product being deeply technical and the company being pre-revenue, only investors with engineering backgrounds were really interested because they could understand and get excited about what we do. That informed us to generate our leads with much narrower focus.

We looked at other OSS & dev tools companies in our batch, looked at who invested in them and asked for intros. Our batchmates were also in the fundraising mode, they knew how hard it can be and they wanted to help, so everything moved very quickly.

We learned not to spend time on non-believers​

As we learned to focus on the highly qualified leads, we also learned that it is very hard (impossible) to change somebody's mind. Plenty of investors liked u and what we do, but they were skeptical about e.g. market size or monetisation potential and made that clear from the start. Many of them were keen to keep chatting, wanted to meet our angel investors etc., but none of that helped change their mind and it was very distracting for us. I believe it is very hard to change somebody's worldview, especially in the seed stage when there is often no strong factual evidence to do so.

Passing through the "valley of death"​

As you can see on the chart, about two months in we barely passed $300k, and we had a whole month with no progress. At the same time, we felt that our pitch got significantly better and we were reaching investors much better suited for us. It was one of the most difficult times, seeing others close their rounds, but we decided to trust in the process and keep going until we have used all the resources we had. It was also the time our lead investor took time to do their own pretty extensive due diligence on Wasp, so although it looks like no progress was made from the outside, a lot of stuff was actually happening behind the scenes.

Suddenly, a few things clicked together from multiple sides and our round was quickly closed, even oversubscribed! It was truly a magical feeling to start closing investors in a single day, even during the first call, when previously it took us weeks to close our first $50k check. The big factor was also that our round was getting filled up and that of course motivated investors to move faster.

We compared ourselves to big, successful companies​

This is one of the best pieces of advice we got from YC partners about fundraising. In the beginning we didn't understand how important this was, but once the meetings started we realised this was one of the best ways to explain the potential of our company to investors. With the innovation in technology that isn't easy to grasp, they needed something to hold on to understand how the business model and distribution could work, and it sounds much more doable if there is a playbook we can follow rather than us reinventing that as well. We kept working on finding a good comparable (we had a few) and explaining in which ways we are similar and why.

Good luck - you can do it!​

I hope you found this helpful and that our story will motivate you to keep going once things get hard! We wish you the best of luck and also feel free to reach out if you'll have any questions.

We are in Beta (try it out)! → Join our community → Work with us

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2021/12/02/waspello.html b/blog/2021/12/02/waspello.html index 96ae4d74a5..42d9692702 100644 --- a/blog/2021/12/02/waspello.html +++ b/blog/2021/12/02/waspello.html @@ -19,15 +19,15 @@ - - + + -
-

How we built a Trello clone with Wasp - Waspello!

· 10 min read
Matija Sosic

Enter Waspello

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.

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Why Trello?​

While building Wasp, our goal is to use it as much as we can to build our projects and play with it, so we can learn what works and what we should do next. This is why Trello was a great choice of app to build with Wasp - it is one of the most well-known full-stack web apps, it's very simple and intuitive to use but also covers a good portion of features used by today's modern web apps.

So let's dig in and see and how it went - what works, what doesn't and, what's missing/coming next!

What works?​

It's alive ⚡🤖 !!​

The good news is all the basic functionality is here - Waspello users can signup/log in which brings them to their project board where they can perform CRUD operations on lists and cards - create them, edit them, move them around, etc. Let's see it in action:

Waspello in action

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

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:

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:

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:

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.

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:

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.

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!). Just to give you an idea, here's a quick glimpse into it:

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.

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.

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.
+

+

How we built a Trello clone with Wasp - Waspello!

· 10 min read
Matija Sosic

Enter Waspello

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.

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Why Trello?​

While building Wasp, our goal is to use it as much as we can to build our projects and play with it, so we can learn what works and what we should do next. This is why Trello was a great choice of app to build with Wasp - it is one of the most well-known full-stack web apps, it's very simple and intuitive to use but also covers a good portion of features used by today's modern web apps.

So let's dig in and see and how it went - what works, what doesn't and, what's missing/coming next!

What works?​

It's alive ⚡🤖 !!​

The good news is all the basic functionality is here - Waspello users can signup/log in which brings them to their project board where they can perform CRUD operations on lists and cards - create them, edit them, move them around, etc. Let's see it in action:

Waspello in action

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

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:

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:

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:

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.

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:

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.

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!). Just to give you an idea, here's a quick glimpse into it:

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.

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.

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:

Waspello - no optimistic UI update
Without an optimistic UI update, there is a delay

You can notice the delay between the moment the card is dropped on the "Done" list and the moment it becomes a part of that list. The reason is that at the moment of dropping the card on "Done" list, the API request with the change is sent to the server, and only when that change is fully processed on the server and saved to the database, the query getListsAndCards returns the correct info and consequently, UI is updated to the correct state.
That is why upon dropping on "Done", the card first goes back to the original list (because the change is not saved in db yet, so useQuery(getListsAndCards) still returns the "old" state), it waits a bit until the API request is processed successfully, and just then the change gets reflected in the UI.

The solution​

A typical approach for solving this issue is to make the client a bit more self-confident, in a way that it doesn't wait for the confirmation from the server but rather immediately updates the UI, at the same time or even before the API request is fired. If it then turns out something went wrong on the server (which typically shouldn't happen), it reverses the change and shows an error message. Thus the name optimistic UI update, since the client assumes in advance that everything will go well to provide a nicer UX.

Waspello - the client being brave
The client when performing an optimistic UI update

This is one of the most complex and error-prone features when developing web apps today and that is why we are super excited to tackle it in Wasp and make the experience as smooth as possible! We are currently in the "figuring out the solution" stage and you can track/join the discussion on GitHub!

What's missing (next features)​

Although it looks super simple at the first glance, Trello is in fact a huge app with lots and lots of cool features hidden under the surface! Here are some of the more obvious ones that are currently not supported in Waspello:

  • Users can have multiple boards, for different projects (currently we have no notion of a "Board" entity in Waspello at all, so there is implicitly only one)
  • Detailed card view - when clicked on a card, a "full" view with extra options opens
  • Search - user can search for a specific list/card
  • Collaboration - multiple users can participate on the same board

And many more - e.g. support for workspaces (next level of the hierarchy, a collection of boards), card labels, filters, ... . It is very helpful to have such a variety of features since we can use it as a testing ground for Wasp and use it as a guiding star towards Beta/1.0!

Become a Waspeller!​

Waspello propaganda
Lightweight Waspello propaganda

If you want to get involved with OSS and at the same time familiarize yourself with Wasp, this is a great way to get started - feel free to choose one of the features listed here or add your own and help us make Waspello the best demo productivity app out there!

Also, make sure to join our community on Discord. We’re always there and are looking forward to seeing what you build!

We are in Beta (try it out)! → Join our community → Work with us

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2021/12/21/shayne-intro.html b/blog/2021/12/21/shayne-intro.html index d26c120198..f104efd1ea 100644 --- a/blog/2021/12/21/shayne-intro.html +++ b/blog/2021/12/21/shayne-intro.html @@ -19,13 +19,13 @@ - - + + -
-

Meet the team - Shayne Czyzewski, Founding Engineer

· 4 min read
Matija Sosic

Welcome Shayne!

Find Shayne on Twitter and GitHub.

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

We are super excited to introduce Shayne, the first person to join the Wasp team! Shayne is a battle-tested veteran engineer, with experiences ranging from leading teams at high-growth startups to working at enterprise giants such as Red Hat and NetApp. Along with that, he is super nice and incredibly pleasant to work with - we are beyond thrilled that he chose Wasp for his next adventure with him and can't wait for you to meet him in our Discord community!

Why did you join Wasp?​

I have always been excited about high-quality dev tooling and web frameworks, and I am also interested in Haskell/compilers. The technology, problem space, and team were just too compelling to pass up. I was also excited to be on the ground floor of a YC startup, where I can have a significant impact and help build a broad, welcoming, open-source community of Wasp developers.

What did you do before?​

I have been a professional developer for over a decade, mostly in backend web development, with experience from Lockheed Martin, Morgan Stanley, NetApp, and Red Hat. Most recently, I was the head of engineering at an edtech company called LearnPlatform, where we were handling a quarter of a billion incoming events per day with the goal of understanding and improving student access to technology that works best for them.

What is your favorite language/framework?​

My favorite framework is probably Ruby on Rails, for the elegance of ideas and seamless implementation. I never had an actual favorite programming language, as I enjoy different aspects of Ruby, Elixir, JavaScript, C#, and others. My least favorite has always been Java. My current favorite language is fast becoming Haskell. :)

The most interesting niche programming language I have used professionally was Ada at Lockheed Martin. We used it to build distributed, real-time, full-motion flight simulators for the military (think multi-million dollar, hyperrealistic multiplayer video games).

What are you most excited about in Wasp?​

As web developers, I think we have gotten accustomed to a certain level of complexity that is not associated with the problem we are solving but the boilerplate of the process. This lack of nuance between accidental and essential complexity has recently led to less than ideal low-code approaches. Wasp, in my view, takes the better approach of a higher-level DSL to abstract some of the typical details using best practices, leaving you to focus on your problem by writing actual code that produces a real web app without any vendor lock-in. That is pretty amazing to me!

How did you start coding?​

Probably by creating some basic LAMP apps in the late 90s while in high school. Growing up, our parents wanted us to have summer jobs to earn money we could spend during the rest of the year. I quickly found that freelance web development on Elance, and similar sites, was more enjoyable and profitable than the alternatives available to 15-year-olds. From then on, I was hooked.

What is your dev setup?​

MacBook Air M1 with an external Dell display, Magic Trackpad, and a split mechanical keyboard from UHK (Ultimate Hacking Keyboard).

camelCase or snake_case?​

I default to whatever the language or codebase conventions are. Visually, I prefer snake case, though (and definitely spaces over tabs). ;)

What's one piece of advice you'd give to an aspiring developer?​

One of the biggest differentiators I have found between good and great engineers is that the great ones possess a continuous desire to learn and grow. They view challenges as fun opportunities to expand their knowledge and skills, recognizing that they always have room for improvement. The corollary is that impostor syndrome is real and never goes away, so try not to be too hard on yourself along the way!

This post was the first of several new hire announcements in the months to come, so stay tuned and reach out if you want to work with Martin, Shayne, and myself!

We are in Beta (try it out)! → Join our community → Work with us

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Meet the team - Shayne Czyzewski, Founding Engineer

· 4 min read
Matija Sosic

Welcome Shayne!

Find Shayne on Twitter and GitHub.

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

We are super excited to introduce Shayne, the first person to join the Wasp team! Shayne is a battle-tested veteran engineer, with experiences ranging from leading teams at high-growth startups to working at enterprise giants such as Red Hat and NetApp. Along with that, he is super nice and incredibly pleasant to work with - we are beyond thrilled that he chose Wasp for his next adventure with him and can't wait for you to meet him in our Discord community!

Why did you join Wasp?​

I have always been excited about high-quality dev tooling and web frameworks, and I am also interested in Haskell/compilers. The technology, problem space, and team were just too compelling to pass up. I was also excited to be on the ground floor of a YC startup, where I can have a significant impact and help build a broad, welcoming, open-source community of Wasp developers.

What did you do before?​

I have been a professional developer for over a decade, mostly in backend web development, with experience from Lockheed Martin, Morgan Stanley, NetApp, and Red Hat. Most recently, I was the head of engineering at an edtech company called LearnPlatform, where we were handling a quarter of a billion incoming events per day with the goal of understanding and improving student access to technology that works best for them.

What is your favorite language/framework?​

My favorite framework is probably Ruby on Rails, for the elegance of ideas and seamless implementation. I never had an actual favorite programming language, as I enjoy different aspects of Ruby, Elixir, JavaScript, C#, and others. My least favorite has always been Java. My current favorite language is fast becoming Haskell. :)

The most interesting niche programming language I have used professionally was Ada at Lockheed Martin. We used it to build distributed, real-time, full-motion flight simulators for the military (think multi-million dollar, hyperrealistic multiplayer video games).

What are you most excited about in Wasp?​

As web developers, I think we have gotten accustomed to a certain level of complexity that is not associated with the problem we are solving but the boilerplate of the process. This lack of nuance between accidental and essential complexity has recently led to less than ideal low-code approaches. Wasp, in my view, takes the better approach of a higher-level DSL to abstract some of the typical details using best practices, leaving you to focus on your problem by writing actual code that produces a real web app without any vendor lock-in. That is pretty amazing to me!

How did you start coding?​

Probably by creating some basic LAMP apps in the late 90s while in high school. Growing up, our parents wanted us to have summer jobs to earn money we could spend during the rest of the year. I quickly found that freelance web development on Elance, and similar sites, was more enjoyable and profitable than the alternatives available to 15-year-olds. From then on, I was hooked.

What is your dev setup?​

MacBook Air M1 with an external Dell display, Magic Trackpad, and a split mechanical keyboard from UHK (Ultimate Hacking Keyboard).

camelCase or snake_case?​

I default to whatever the language or codebase conventions are. Visually, I prefer snake case, though (and definitely spaces over tabs). ;)

What's one piece of advice you'd give to an aspiring developer?​

One of the biggest differentiators I have found between good and great engineers is that the great ones possess a continuous desire to learn and grow. They view challenges as fun opportunities to expand their knowledge and skills, recognizing that they always have room for improvement. The corollary is that impostor syndrome is real and never goes away, so try not to be too hard on yourself along the way!

This post was the first of several new hire announcements in the months to come, so stay tuned and reach out if you want to work with Martin, Shayne, and myself!

We are in Beta (try it out)! → Join our community → Work with us

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/01/27/waspleau.html b/blog/2022/01/27/waspleau.html index 25f78d81b1..b1f177951b 100644 --- a/blog/2022/01/27/waspleau.html +++ b/blog/2022/01/27/waspleau.html @@ -19,13 +19,13 @@ - - + + -
-

Build a metrics dashboard with background jobs in Wasp - Say hello to Waspleau!

· 5 min read
Shayne Czyzewski

Hello, Waspleau

See Waspleau here! | See the code

We've built a dashboard powered by a job queue using Wasp!

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Measure all the metrics!

Hello, Waspleau!​

Let’s face it - metrics are all around us. Wouldn’t it be great if there was a quick and easy way to build a nice-looking metrics dashboard from data pulled in by HTTP calls to many different sources, cache the data in-memory, and periodically update it via background jobs? Why yes, yes it would... so we made an example Wasp app called Waspleau that does just that!

Here is what it looks like live: https://waspleau-app-client.fly.dev/ There is also a screenshot at the top of this post for those who refrain from clicking on any unknown web links for fear of being Rickrolled. Respect.

“Show me the code”​

So, what do we need to get started? First, we need a way to schedule and run jobs; for this, we decided to use Bull. Ok, let’s wire it up. This should be easy, right? We can add external NPM dependencies in our Wasp files like so:

main.wasp
app waspleau {
  title: "Waspleau",

  dependencies: [
    ("bull", "4.1.1"),
    ("axios", "^0.21.1")
  ]
}

But where do we declare our queue and processing callback functions in Wasp? Uh oh...

Sad

server.setupFn for queue setup​

Thankfully, Waspleau can leverage a powerful and flexible hook supplied by Wasp called server.setupFn. This declares a JavaScript function that will be executed on server start. Yahoo! This means we can do things like the following:

main.wasp
app waspleau {
  ...

  server: {
    setupFn: import serverSetup from "@server/serverSetup.js"
  }
}
src/server/serverSetup.js
import Queue from 'bull'

const queue = new Queue('waspleau', process.env.REDIS_URL || 'redis://127.0.0.1:6379',
  { defaultJobOptions: { removeOnComplete: true } }
)

queue.process('*', async (job) => { ... })

export default async () => {
  // To initially populate the queue, we can do:
  await queue.add({ ... }) // first run, one-off job
  await queue.add({ ... }, { repeat: { cron: '*/10 * * * *' } }) // recurring job
}

Abstracting workers and job processing​

Awesome, we can now enqueue and process background jobs, but how can we make it easy to create many different kinds of jobs and schedule them to run at different intervals? For Waspleau, we created our own type of worker object convention to help standardize and simplify adding more:

src/server/workers/template.js
const workerFunction = async (opts) => {
  return [
    { name: 'Metric 1 name', value: 'foo', updatedAt: ... },
    { name: 'Metric 2 name', value: 'bar', updatedAt: ... },
  ]
}

export const workerTemplate = { name: 'Job Name', fn: workerFunction, schedule: '*/10 * * * *' }

With this workerFunction setup, we can return one or more metrics per worker type. Waspleau can easily use any module that exports this shape. Here is a real example from the demo that makes HTTP calls to GitHub’s API with Axios:

src/server/workers/github.js
import axios from 'axios'

const workerFunction = async (opts) => {
  console.log('github.js workerFunction')

  const now = Date.now()

  try {
    const response = await axios.get('https://api.github.com/repos/wasp-lang/wasp')

    return [
      { name: 'Wasp GitHub Stars', value: response.data.stargazers_count, updatedAt: now },
      { name: 'Wasp GitHub Language', value: response.data.language, updatedAt: now },
      { name: 'Wasp GitHub Forks', value: response.data.forks, updatedAt: now },
      { name: 'Wasp GitHub Open Issues', value: response.data.open_issues, updatedAt: now },
    ]
  } catch (error) {
    console.error(error)
    return []
  }
}

export const githubWorker = { name: 'GitHub API', fn: workerFunction, schedule: '*/10 * * * *' }

Note: Please see the actual serverSetup.js file for how we use this abstraction in practice.

Server → client​

We now have jobs running and data updating at regular intervals, nice, but we still need a way to send that data down the wire. Here, we expose the in-memory data from our server.setupFn module so our queries can also use it:

main.wasp
...

query dashboard {
  fn: import { refreshDashboardData } from "@server/dashboard.js"
}
src/server/dashboard.js
import { getDashboardData } from './serverSetup.js'

export const refreshDashboardData = async (_args, _context) => {
  return getDashboardData()
}
src/server/serverSetup.js
...

const dashboardData = {} // This is updated in the queue process callback
export const getDashboardData = () => Object.values(dashboardData).flat()

From there, we can request it on the frontend in React components as usual and also set a one-minute client-side refetch interval just for good measure:

src/client/MainPage.js
...

const { data: dashboardData, isFetching, error } = useQuery(refreshDashboardData, null, { refetchInterval: 60 * 1000 })

...

Congratulations, let’s dance!​

Whew, we did it! If you’d like to deploy your own customized version of this dashboard, please clone our repo and check out the Waspleau example README.md for tips on getting started. You can also check out our docs to dive deeper into anything.

Rickroll

Still got ya! :D

2022 is going to be exciting 🚀​

While this functionality currently exists outside of Wasp, keep an eye on our roadmap as we head toward 1.0. We will be busy adding lots of great features to our Wasp DSL in the coming months that will supercharge your web development experience! Thanks for reading, and please feel free to connect with us in Discord about using Wasp on your next project.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Build a metrics dashboard with background jobs in Wasp - Say hello to Waspleau!

· 5 min read
Shayne Czyzewski

Hello, Waspleau

See Waspleau here! | See the code

We've built a dashboard powered by a job queue using Wasp!

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Measure all the metrics!

Hello, Waspleau!​

Let’s face it - metrics are all around us. Wouldn’t it be great if there was a quick and easy way to build a nice-looking metrics dashboard from data pulled in by HTTP calls to many different sources, cache the data in-memory, and periodically update it via background jobs? Why yes, yes it would... so we made an example Wasp app called Waspleau that does just that!

Here is what it looks like live: https://waspleau-app-client.fly.dev/ There is also a screenshot at the top of this post for those who refrain from clicking on any unknown web links for fear of being Rickrolled. Respect.

“Show me the code”​

So, what do we need to get started? First, we need a way to schedule and run jobs; for this, we decided to use Bull. Ok, let’s wire it up. This should be easy, right? We can add external NPM dependencies in our Wasp files like so:

main.wasp
app waspleau {
  title: "Waspleau",

  dependencies: [
    ("bull", "4.1.1"),
    ("axios", "^0.21.1")
  ]
}

But where do we declare our queue and processing callback functions in Wasp? Uh oh...

Sad

server.setupFn for queue setup​

Thankfully, Waspleau can leverage a powerful and flexible hook supplied by Wasp called server.setupFn. This declares a JavaScript function that will be executed on server start. Yahoo! This means we can do things like the following:

main.wasp
app waspleau {
  ...

  server: {
    setupFn: import serverSetup from "@server/serverSetup.js"
  }
}
src/server/serverSetup.js
import Queue from 'bull'

const queue = new Queue('waspleau', process.env.REDIS_URL || 'redis://127.0.0.1:6379',
  { defaultJobOptions: { removeOnComplete: true } }
)

queue.process('*', async (job) => { ... })

export default async () => {
  // To initially populate the queue, we can do:
  await queue.add({ ... }) // first run, one-off job
  await queue.add({ ... }, { repeat: { cron: '*/10 * * * *' } }) // recurring job
}

Abstracting workers and job processing​

Awesome, we can now enqueue and process background jobs, but how can we make it easy to create many different kinds of jobs and schedule them to run at different intervals? For Waspleau, we created our own type of worker object convention to help standardize and simplify adding more:

src/server/workers/template.js
const workerFunction = async (opts) => {
  return [
    { name: 'Metric 1 name', value: 'foo', updatedAt: ... },
    { name: 'Metric 2 name', value: 'bar', updatedAt: ... },
  ]
}

export const workerTemplate = { name: 'Job Name', fn: workerFunction, schedule: '*/10 * * * *' }

With this workerFunction setup, we can return one or more metrics per worker type. Waspleau can easily use any module that exports this shape. Here is a real example from the demo that makes HTTP calls to GitHub’s API with Axios:

src/server/workers/github.js
import axios from 'axios'

const workerFunction = async (opts) => {
  console.log('github.js workerFunction')

  const now = Date.now()

  try {
    const response = await axios.get('https://api.github.com/repos/wasp-lang/wasp')

    return [
      { name: 'Wasp GitHub Stars', value: response.data.stargazers_count, updatedAt: now },
      { name: 'Wasp GitHub Language', value: response.data.language, updatedAt: now },
      { name: 'Wasp GitHub Forks', value: response.data.forks, updatedAt: now },
      { name: 'Wasp GitHub Open Issues', value: response.data.open_issues, updatedAt: now },
    ]
  } catch (error) {
    console.error(error)
    return []
  }
}

export const githubWorker = { name: 'GitHub API', fn: workerFunction, schedule: '*/10 * * * *' }

Note: Please see the actual serverSetup.js file for how we use this abstraction in practice.

Server → client​

We now have jobs running and data updating at regular intervals, nice, but we still need a way to send that data down the wire. Here, we expose the in-memory data from our server.setupFn module so our queries can also use it:

main.wasp
...

query dashboard {
  fn: import { refreshDashboardData } from "@server/dashboard.js"
}
src/server/dashboard.js
import { getDashboardData } from './serverSetup.js'

export const refreshDashboardData = async (_args, _context) => {
  return getDashboardData()
}
src/server/serverSetup.js
...

const dashboardData = {} // This is updated in the queue process callback
export const getDashboardData = () => Object.values(dashboardData).flat()

From there, we can request it on the frontend in React components as usual and also set a one-minute client-side refetch interval just for good measure:

src/client/MainPage.js
...

const { data: dashboardData, isFetching, error } = useQuery(refreshDashboardData, null, { refetchInterval: 60 * 1000 })

...

Congratulations, let’s dance!​

Whew, we did it! If you’d like to deploy your own customized version of this dashboard, please clone our repo and check out the Waspleau example README.md for tips on getting started. You can also check out our docs to dive deeper into anything.

Rickroll

Still got ya! :D

2022 is going to be exciting 🚀​

While this functionality currently exists outside of Wasp, keep an eye on our roadmap as we head toward 1.0. We will be busy adding lots of great features to our Wasp DSL in the coming months that will supercharge your web development experience! Thanks for reading, and please feel free to connect with us in Discord about using Wasp on your next project.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/05/31/filip-intro.html b/blog/2022/05/31/filip-intro.html index bdaa702a0a..dc3f3150d9 100644 --- a/blog/2022/05/31/filip-intro.html +++ b/blog/2022/05/31/filip-intro.html @@ -19,12 +19,12 @@ - - + + -
-

Meet the team - Filip Sodić, Founding Engineer

· 6 min read
Matija Sosic

Welcome Filip!

Find Filip on GitHub.

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

We are immensely excited to welcome Filip, our latest Founding Software +

+

Meet the team - Filip Sodić, Founding Engineer

· 6 min read
Matija Sosic

Welcome Filip!

Find Filip on GitHub.

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

We are immensely excited to welcome Filip, our latest Founding Software Engineer! Filip is an experienced engineer and a passionate computer scientist - his two biggest passions are building compilers/designing programming languages and web development (what a lucky coincidence, right? @@ -78,7 +78,7 @@ projects because you think they aren’t ready yet. Good enough sometimes truly is good enough and things can often be considered done before you consider them done.

I still occasionally need to give this advice to myself :).

Lastly, where can people find or connect with you online?​

GitHub: https://github.com/sodic

LinkedIn: https://www.linkedin.com/in/filipsodic/

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2022/06/01/gitpod-hackathon-guide.html b/blog/2022/06/01/gitpod-hackathon-guide.html index 9fd588a0a0..c96783f05a 100644 --- a/blog/2022/06/01/gitpod-hackathon-guide.html +++ b/blog/2022/06/01/gitpod-hackathon-guide.html @@ -19,13 +19,13 @@ - - + + -
-

How to win a hackathon. Brief manual.

· 4 min read

Wasp app deploye to Gitpod

"All good thoughts and ideas mean nothing without the proper tools to achieve them."
>Jason Statham

TL;DR: Wasp allows you to build and deploy a full-stack JS web app with a single config file. Gitpod spins up fresh, automated developer environments in the cloud, in seconds. A perfect tandem to win a hackathon and enjoy free pizza even before other teams even started to set up their coding env and realized they need to update their node version.

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Intro:​

Usually, every hackathon starts from similar activities:

  1. setting up a local dev environment, especially if all the team members use different operating systems. There are always issues with the SDK/packages/compiler, etc.
  2. building project backbone (folder structure, basic services, CRUD APIs, and so on).

Both of them are time-consuming, boring, and cause issues.

Dealing with routine might be frustrating

Thankfully, those issues can be avoided! Gitpod allows you to spin up a clean, already pre-set dev environment. And Wasp enables you to build a full-stack JS web app with a single config file (alongside your React and Node.js code). But first things first.

Pennywise luring into his openspace

Dev environment setup:​

Gitpod spins up a bespoke dev environment in the cloud for any git branch (once you configured it for your project), on-demand. So you can start coding right away. Build, debug, commit and push your code in seconds, without any local SDK issues. After you’ve finished – you can host your app after a couple of clicks and share the project with your teammate. You can even make changes to the same project simultaneously, leveraging a pair programming approach.

Since Gitpod is a cloud-based workspace – spinning up a new application takes a couple of clicks.

  1. Fork https://github.com/gitpod-io/template-wasp and give it a meaningful name, e.g. “My Awesome Recipes App” -> this is now a repo for your new web app.
  2. In your newly created repo, check the Readme and click the “Open in Gitpod” button
  3. Login via Github
  4. Allow pop-ups
  5. That’s it! Enjoy your fresh cloud-based dev environment!

Pennywise luring to take part in hackathon

An optional thing might be enabling the “Share” option to make the app accessible from the external internet.

How to share a workspace

You can pick up one of the following IDE’s, switch between light/dark themes and you can even install all your favorite extensions.

Gitpod IDE types

So, eventually, the workflow can look like this: someone from the team forks the template repo and shares it with others. Teammates open this repo in Gitpod, creating their own dev branches.

Voila! 🥳

The whole team is ready to code in a matter of seconds. After the team is done with the development, someone can pull all the changes, share the project, and present it to the judges.

No need to fix local issues, ensure the Node version is aligned, or configure the deployment pipeline for DigitalOcean. Gitpod does all development preparations. The only thing the team has to do – is to implement the idea ASAP. And here Wasp comes into play!

Building project backbone:​

Ok, we’ve successfully set up a shared dev environment. It’s time to create a production-ready web app with just a few lines of code. Based on your needs – you can declare separate pages, routes, database models, etc. - it’s super easy and intuitive!

The ideal case would be to:

  1. Check out the language overview: https://wasp-lang.dev/docs/general/language
  2. Follow a 20-minutes tutorial on how to build a To-Do app with Wasp: https://wasp-lang.dev/docs/tutorial/create

It may seem a bit inconvenient: why spend time on learning, when you already can start building something meaningful? The short answer is: time-saving. Wasp’s main point is to set you free from building time-consuming boilerplate. So even if you’ll spend half of an hour learning the basics – you’ll still be able to outrun other hackathon participants. While they will be copy-pasting CRUD API methods – you’ll be building business logic.

And 20 minutes is time well spent to become more productive. Setting up each team member's environment locally likely takes more than 20 minutes if you don't use Gitpod.

To wrap up:​

We think that Wasp + Gitpod is a powerful toolset for speedrunning any hackathon. No matter how complex or ambitious your project is. If it’s built with Node and React – nothing can stop you from winning. Good luck, have fun, and enjoy that pizza 🍕!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

How to win a hackathon. Brief manual.

· 4 min read

Wasp app deploye to Gitpod

"All good thoughts and ideas mean nothing without the proper tools to achieve them."
>Jason Statham

TL;DR: Wasp allows you to build and deploy a full-stack JS web app with a single config file. Gitpod spins up fresh, automated developer environments in the cloud, in seconds. A perfect tandem to win a hackathon and enjoy free pizza even before other teams even started to set up their coding env and realized they need to update their node version.

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Intro:​

Usually, every hackathon starts from similar activities:

  1. setting up a local dev environment, especially if all the team members use different operating systems. There are always issues with the SDK/packages/compiler, etc.
  2. building project backbone (folder structure, basic services, CRUD APIs, and so on).

Both of them are time-consuming, boring, and cause issues.

Dealing with routine might be frustrating

Thankfully, those issues can be avoided! Gitpod allows you to spin up a clean, already pre-set dev environment. And Wasp enables you to build a full-stack JS web app with a single config file (alongside your React and Node.js code). But first things first.

Pennywise luring into his openspace

Dev environment setup:​

Gitpod spins up a bespoke dev environment in the cloud for any git branch (once you configured it for your project), on-demand. So you can start coding right away. Build, debug, commit and push your code in seconds, without any local SDK issues. After you’ve finished – you can host your app after a couple of clicks and share the project with your teammate. You can even make changes to the same project simultaneously, leveraging a pair programming approach.

Since Gitpod is a cloud-based workspace – spinning up a new application takes a couple of clicks.

  1. Fork https://github.com/gitpod-io/template-wasp and give it a meaningful name, e.g. “My Awesome Recipes App” -> this is now a repo for your new web app.
  2. In your newly created repo, check the Readme and click the “Open in Gitpod” button
  3. Login via Github
  4. Allow pop-ups
  5. That’s it! Enjoy your fresh cloud-based dev environment!

Pennywise luring to take part in hackathon

An optional thing might be enabling the “Share” option to make the app accessible from the external internet.

How to share a workspace

You can pick up one of the following IDE’s, switch between light/dark themes and you can even install all your favorite extensions.

Gitpod IDE types

So, eventually, the workflow can look like this: someone from the team forks the template repo and shares it with others. Teammates open this repo in Gitpod, creating their own dev branches.

Voila! 🥳

The whole team is ready to code in a matter of seconds. After the team is done with the development, someone can pull all the changes, share the project, and present it to the judges.

No need to fix local issues, ensure the Node version is aligned, or configure the deployment pipeline for DigitalOcean. Gitpod does all development preparations. The only thing the team has to do – is to implement the idea ASAP. And here Wasp comes into play!

Building project backbone:​

Ok, we’ve successfully set up a shared dev environment. It’s time to create a production-ready web app with just a few lines of code. Based on your needs – you can declare separate pages, routes, database models, etc. - it’s super easy and intuitive!

The ideal case would be to:

  1. Check out the language overview: https://wasp-lang.dev/docs/general/language
  2. Follow a 20-minutes tutorial on how to build a To-Do app with Wasp: https://wasp-lang.dev/docs/tutorial/create

It may seem a bit inconvenient: why spend time on learning, when you already can start building something meaningful? The short answer is: time-saving. Wasp’s main point is to set you free from building time-consuming boilerplate. So even if you’ll spend half of an hour learning the basics – you’ll still be able to outrun other hackathon participants. While they will be copy-pasting CRUD API methods – you’ll be building business logic.

And 20 minutes is time well spent to become more productive. Setting up each team member's environment locally likely takes more than 20 minutes if you don't use Gitpod.

To wrap up:​

We think that Wasp + Gitpod is a powerful toolset for speedrunning any hackathon. No matter how complex or ambitious your project is. If it’s built with Node and React – nothing can stop you from winning. Good luck, have fun, and enjoy that pizza 🍕!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/06/15/jobs-feature-announcement.html b/blog/2022/06/15/jobs-feature-announcement.html index 3f612ed271..b1fa033585 100644 --- a/blog/2022/06/15/jobs-feature-announcement.html +++ b/blog/2022/06/15/jobs-feature-announcement.html @@ -19,13 +19,13 @@ - - + + -
-

Feature Announcement - Wasp Jobs

· 7 min read
Shayne Czyzewski

You get a job!

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Storytime​

Storytime

Imagine you are working on the next unicorn SaaS web app and need to send a user an email, manipulate an uploaded image via an external API call, or recalculate some internal metrics every night. (Or, maybe you’re doing some fancy blockchain thing for that frothy investment multiple; :D whatever it is, just envision an operation that may take a significant amount of time and/or fail.) How would you implement this?

Spinning!

You wouldn’t want the server to delay sending its HTTP response until those are done (unless you are one of those people who love seeing the Mac spinning icon), so you'll need something out-of-band from the normal request-response flow. Even in an event-loop-based system like Node.js, just calling an async function isn't ideal since you will need to handle failures, retries, and throttling, amongst other concerns. And sometimes we need to schedule tasks to run in the future, or repeatedly, so we need a completely different toolset.

The typical solution here is to use a job queue of some kind. They are not impossible to set up, of course, but there is a fair amount of boilerplate involved, some operational expertise/overhead required, and moving from one system to another when you outgrow it is usually a challenge. These are the exact areas where we feel Wasp can provide real value, so we are happy to introduce Wasp Jobs to help out with this!

src/server/workers/github.js
import axios from 'axios'
import { upsertMetric } from './utils.js'

export async function workerFunction() {
  const response = await axios.get('https://api.github.com/repos/wasp-lang/wasp')

  const metrics = [
    { name: 'Wasp GitHub Stars', value: response.data.stargazers_count },
    { name: 'Wasp GitHub Language', value: response.data.language },
    { name: 'Wasp GitHub Forks', value: response.data.forks },
    { name: 'Wasp GitHub Open Issues', value: response.data.open_issues },
  ]

  await Promise.all(metrics.map(upsertMetric))

  return metrics
}

Wasp allows you to write a regular async JavaScript function (like the one above that gathers GitHub metrics and stores them in the DB) and have it run within the context of a job queue system, which we call an executor. You can manually submit work to be done on the server, or specify a cron schedule to have your job automatically invoked. And, best of all, as we add more job executors in the future, you can change where it runs on a single line in your .wasp file.

Most jobs have a boss. Our first job executor is a... pg-boss. 😅​

Eeek
Me trying to lay off the job-related puns. Ok, ok, I’ll quit. Ahhh!

In my prior life as a Ruby on Rails developer, the decision of how to implement jobs was pretty simple. You had Active Job at your disposal, and for backends, you would use something like Sidekiq or Delayed Job. In a similarly paved path, Python developers would have likely looked first to Celery.

In the JavaScript world, Bull is quite popular these days. However, we decided to use pg-boss, as it too provides persistence, delayed jobs, and schedules (plus many other features). But critically, pg-boss uses PostgreSQL instead of Redis (like Bull) for storage and coordination, and this was important since we did not want to introduce any new infrastructure dependencies to our existing production stack.

But isn’t a database as a queue an anti-pattern, you may ask? Well, historically I’d probably say yes. However, PostgreSQL 9.5 added SKIP LOCKED, which it specifically mentions can aid in avoiding lock contention with multiple consumer queue-like workloads [https://www.postgresql.org/docs/9.5/sql-select.html#SQL-FOR-UPDATE-SHARE]. So for the low-volume background job workloads that many apps have, we feel using a database as a queue is a great compromise and starting point for many users from a benefit vs. complexity perspective.

However, we will also continue to expand the number of job execution runtimes we support. Let us know in Discord what you’d like to see next!

Real Example - Updating Waspleau​

If you are a regular reader of this blog (thank you, you deserve a raise! 😊), you may recall we created an example app of a metrics dashboard called Waspleau that used workers in the background to make periodic HTTP calls for data. In that example, we didn’t yet have access to recurring jobs in Wasp, so we used Bull for scheduled jobs instead. To set up our queue-related logic we had to have this huge setupFn wiring it all up; but now, we can remove all that code and simply use jobs instead! Here is what the new DSL looks like:

main.wasp
// A cron job for fetching GitHub stats
job getGithubStats {
  executor: PgBoss,
  perform: {
    fn: import { workerFunction } from "@server/workers/github.js"
  },
  schedule: {
    cron: "*/10 * * * *"
  }
}

// A cron job to measure how long a webpage takes to load
job calcPageLoadTime {
  executor: PgBoss,
  perform: {
    fn: import { workerFunction } from "@server/workers/loadTime.js"
  },
  schedule: {
    cron: "*/5 * * * *",
    args: {=json {
      "url": "https://wasp-lang.dev",
      "name": "wasp-lang.dev Load Time"
    } json=}
  }
}

And here is an example of how you can reference and invoke jobs on the server. Note: We did not even need to do this step since jobs with a schedule are automatically configured to run at the desired time.

src/server/serverSetup.js
/**
* These Jobs are automatically scheduled by Wasp.
* However, let's kick them off on server setup to ensure we have data right away.
*/
import { github } from '@wasp/jobs/getGithubStats.js'
import { loadTime } from '@wasp/jobs/calcPageLoadTime.js'

export default async function () {
  await github.submit()
  await loadTime.submit({
    url: "https://wasp-lang.dev",
    name: "wasp-lang.dev Load Time"
  })
}

And voila, it is really that simple. Wasp takes care of setting up pg-boss and hooking up all your job callbacks, leaving you to focus on what matters- your own code. Here is a visual of what is happening behind the scenes:

Architecture

For those interested, check out the full diff here and weep with joy for all those boilerplate lines of code we fired! We were also able to ax Redis from our infrastructure!

Looks neat! What’s next?​

First off, please check out our docs for Jobs. There, you will find all the info you need to start using them. Next, if you want to see the code for this example in full, you can find it here: https://github.com/wasp-lang/wasp/tree/release/examples/waspleau

In the future, we plan to add more job executors, including support for polyglot workers (imagine running your Python ML function from Wasp!). We are also open to any other ideas on how jobs can become more useful to you (like client-side access to server-side jobs, or client-side jobs using similar abstractions?). Let us know what you think!

Special thanks to Tim Jones for his hard work building an amazing OSS library, pg-boss, and for reviewing this post. Please consider supporting that project if it solves your needs!
Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Feature Announcement - Wasp Jobs

· 7 min read
Shayne Czyzewski

You get a job!

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Storytime​

Storytime

Imagine you are working on the next unicorn SaaS web app and need to send a user an email, manipulate an uploaded image via an external API call, or recalculate some internal metrics every night. (Or, maybe you’re doing some fancy blockchain thing for that frothy investment multiple; :D whatever it is, just envision an operation that may take a significant amount of time and/or fail.) How would you implement this?

Spinning!

You wouldn’t want the server to delay sending its HTTP response until those are done (unless you are one of those people who love seeing the Mac spinning icon), so you'll need something out-of-band from the normal request-response flow. Even in an event-loop-based system like Node.js, just calling an async function isn't ideal since you will need to handle failures, retries, and throttling, amongst other concerns. And sometimes we need to schedule tasks to run in the future, or repeatedly, so we need a completely different toolset.

The typical solution here is to use a job queue of some kind. They are not impossible to set up, of course, but there is a fair amount of boilerplate involved, some operational expertise/overhead required, and moving from one system to another when you outgrow it is usually a challenge. These are the exact areas where we feel Wasp can provide real value, so we are happy to introduce Wasp Jobs to help out with this!

src/server/workers/github.js
import axios from 'axios'
import { upsertMetric } from './utils.js'

export async function workerFunction() {
  const response = await axios.get('https://api.github.com/repos/wasp-lang/wasp')

  const metrics = [
    { name: 'Wasp GitHub Stars', value: response.data.stargazers_count },
    { name: 'Wasp GitHub Language', value: response.data.language },
    { name: 'Wasp GitHub Forks', value: response.data.forks },
    { name: 'Wasp GitHub Open Issues', value: response.data.open_issues },
  ]

  await Promise.all(metrics.map(upsertMetric))

  return metrics
}

Wasp allows you to write a regular async JavaScript function (like the one above that gathers GitHub metrics and stores them in the DB) and have it run within the context of a job queue system, which we call an executor. You can manually submit work to be done on the server, or specify a cron schedule to have your job automatically invoked. And, best of all, as we add more job executors in the future, you can change where it runs on a single line in your .wasp file.

Most jobs have a boss. Our first job executor is a... pg-boss. 😅​

Eeek
Me trying to lay off the job-related puns. Ok, ok, I’ll quit. Ahhh!

In my prior life as a Ruby on Rails developer, the decision of how to implement jobs was pretty simple. You had Active Job at your disposal, and for backends, you would use something like Sidekiq or Delayed Job. In a similarly paved path, Python developers would have likely looked first to Celery.

In the JavaScript world, Bull is quite popular these days. However, we decided to use pg-boss, as it too provides persistence, delayed jobs, and schedules (plus many other features). But critically, pg-boss uses PostgreSQL instead of Redis (like Bull) for storage and coordination, and this was important since we did not want to introduce any new infrastructure dependencies to our existing production stack.

But isn’t a database as a queue an anti-pattern, you may ask? Well, historically I’d probably say yes. However, PostgreSQL 9.5 added SKIP LOCKED, which it specifically mentions can aid in avoiding lock contention with multiple consumer queue-like workloads [https://www.postgresql.org/docs/9.5/sql-select.html#SQL-FOR-UPDATE-SHARE]. So for the low-volume background job workloads that many apps have, we feel using a database as a queue is a great compromise and starting point for many users from a benefit vs. complexity perspective.

However, we will also continue to expand the number of job execution runtimes we support. Let us know in Discord what you’d like to see next!

Real Example - Updating Waspleau​

If you are a regular reader of this blog (thank you, you deserve a raise! 😊), you may recall we created an example app of a metrics dashboard called Waspleau that used workers in the background to make periodic HTTP calls for data. In that example, we didn’t yet have access to recurring jobs in Wasp, so we used Bull for scheduled jobs instead. To set up our queue-related logic we had to have this huge setupFn wiring it all up; but now, we can remove all that code and simply use jobs instead! Here is what the new DSL looks like:

main.wasp
// A cron job for fetching GitHub stats
job getGithubStats {
  executor: PgBoss,
  perform: {
    fn: import { workerFunction } from "@server/workers/github.js"
  },
  schedule: {
    cron: "*/10 * * * *"
  }
}

// A cron job to measure how long a webpage takes to load
job calcPageLoadTime {
  executor: PgBoss,
  perform: {
    fn: import { workerFunction } from "@server/workers/loadTime.js"
  },
  schedule: {
    cron: "*/5 * * * *",
    args: {=json {
      "url": "https://wasp-lang.dev",
      "name": "wasp-lang.dev Load Time"
    } json=}
  }
}

And here is an example of how you can reference and invoke jobs on the server. Note: We did not even need to do this step since jobs with a schedule are automatically configured to run at the desired time.

src/server/serverSetup.js
/**
* These Jobs are automatically scheduled by Wasp.
* However, let's kick them off on server setup to ensure we have data right away.
*/
import { github } from '@wasp/jobs/getGithubStats.js'
import { loadTime } from '@wasp/jobs/calcPageLoadTime.js'

export default async function () {
  await github.submit()
  await loadTime.submit({
    url: "https://wasp-lang.dev",
    name: "wasp-lang.dev Load Time"
  })
}

And voila, it is really that simple. Wasp takes care of setting up pg-boss and hooking up all your job callbacks, leaving you to focus on what matters- your own code. Here is a visual of what is happening behind the scenes:

Architecture

For those interested, check out the full diff here and weep with joy for all those boilerplate lines of code we fired! We were also able to ax Redis from our infrastructure!

Looks neat! What’s next?​

First off, please check out our docs for Jobs. There, you will find all the info you need to start using them. Next, if you want to see the code for this example in full, you can find it here: https://github.com/wasp-lang/wasp/tree/release/examples/waspleau

In the future, we plan to add more job executors, including support for polyglot workers (imagine running your Python ML function from Wasp!). We are also open to any other ideas on how jobs can become more useful to you (like client-side access to server-side jobs, or client-side jobs using similar abstractions?). Let us know what you think!

Special thanks to Tim Jones for his hard work building an amazing OSS library, pg-boss, and for reviewing this post. Please consider supporting that project if it solves your needs!
Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/06/24/ML-code-gen-vs-coding-by-hand-future.html b/blog/2022/06/24/ML-code-gen-vs-coding-by-hand-future.html index 43dc5dcd21..1a603db20f 100644 --- a/blog/2022/06/24/ML-code-gen-vs-coding-by-hand-future.html +++ b/blog/2022/06/24/ML-code-gen-vs-coding-by-hand-future.html @@ -19,13 +19,13 @@ - - + + -
-

ML code generation vs. coding by hand - what we think programming is going to look like

· 11 min read
Matija Sosic

We are working on a config language / DSL for building web apps that integrates with React & Node.js. A number of times we've been asked “Why are you bothering creating a new language for web app development? Isn’t Github Copilot* soon going to be generating all the code for developers anyhow?”.

This is on our take on the situation and what we think things might look like in the future.

Trending post!

This post was trending on HackerNews - you can see the discussion here.

Why (ML) code generation?​

In order to make development faster, we came up with IDE autocompletion - e.g. if you are using React and start typing componentDid, IDE will automatically offer to complete it to componentDidMount() or componentDidLoad(). Besides saving keystrokes, maybe even more valuable is being able to see what methods/properties are available to us within a current scope. IDE being aware of the project structure and code hierarchy also makes refactoring much easier.

Although that’s already great, how do we take it to the next level? Traditional IDE support is based on rules written by humans and if we e.g. wanted to make IDE capable of implementing common functions for us, there would be just too many of them to catalogize and maintain by hand.

If there was only a way for a computer to analyze all the code we’ve written so far and learn by itself how to autocomplete our code and what to do about humanity in general, instead of us doing all the hard work ...

Delicious and moist cake aside, we actually have this working! Thanks to the latest advances in machine learning, IDEs can now do some really cool things like proposing the full implementation of a function, based on its name and the accompanying comments:

Copilot example - text sentiment
GitHub Copilot generating a whole function body based on its signature and the comments on top of it.

This is pretty amazing! The example above is powered by Github Copilot - it’s essentially a neural network trained on a huge amount of publicly available code. I will not get into the technical details of how it works under the hood, but there are lots of great articles covering the science behind it.

Seeing this, questions arise - what does this mean for the future of programming? Is this just IDE autocompletion on steroids or something more? Do we need to keep bothering with manually writing code, if we can just type in the comments what we want and that’s it?

Who maintains the code once it’s generated?​

When thinking about how ML code generation affects the overall development process, there is one thing to consider that often doesn’t immediately spring to mind when looking at the impressive Copilot examples.

note

For the purposes of this post, I will not delve into the questions of code quality, security, legal & privacy issues, pricing, and others of similar character that are often brought up in these early days of ML code generation. Let’s just assume all this is sorted out and see what happens next.

The question is - what happens with the code once it is generated? Who is responsible for it and who will maintain and refactor it in the future?

Devs still need to maintain generated code

Although ML code generation helps with getting the initial code written, it cannot do much beyond that - if that code is to be maintained and changed in the future (and if anyone uses the product, it is), the developer still needs to fully own and understand it.

Imagine all we had was an assembly language, but IDE completion worked really well for it, and you could say “implement a function that sorts an array, ascending” and it would produce the required code perfectly. Would that still be something you’d like to return to in the future once you need to change your sort to descending 😅 ?

In other words, it means Copilot and similar solutions do not reduce the code complexity nor the amount of knowledge required to build features, they just help write the initial code faster, and bring the knowledge/examples closer to the code (which is really helpful). If a developer accepts the generated code blindly, they are just creating tech debt and pushing it forward.

Meet the big A - Abstraction 👆​

If Github Copilot and others cannot solve all our troubles of learning how to code and understanding in detail how session management via JWT works, what can?

Abstraction - that’s how programmers have been dealing with the code repetition and reducing complexity for decades - by creating libraries, frameworks, and languages. It is how we advanced from vanilla JS and direct DOM manipulation to jQuery and finally to UI libraries such as React and Vue.

Introducing abstractions inevitably means giving up on a certain amount of power and flexibility (e.g. when summing numbers in Python you don’t get to exactly specify which CPU registers are going to be used for it), but the point is that, if done right, you don’t need nor want such power in the majority of the cases.

Abstraction equals less responsibility
What Uncle Ben actually meant: avoiding responsibility is the main benefit of abstraction! (Peter totally missed the point, unfortunately, and became Spiderman instead of learning how to code)

The only way not to be responsible for a piece of code is that it doesn’t exist in the first place.

Because as soon as pixels on the screen change their color it’s something you have to worry about, and that is why the main benefit of all frameworks, languages, etc. is less code == less decisions == less responsibility.

The only way to have less code is to make less decisions and provide fewer details to the computer on how to do a certain task - ideally, we’d just state what we want and we wouldn’t even care about how it is done, as long as it’s within the time/memory/cost boundaries we have (so we might need to state those as well).

Let’s take a look at the very common (and everyone’s favorite) feature in the world of web apps - authentication (yaay ☠️ 🔫)! The typical code for it will look something like this:

Auth on the backend in Node.js - example
import jwt from 'jsonwebtoken'
import SecurePassword from 'secure-password'
import util from 'util'

import prisma from '../dbClient.js'
import { handleRejection } from '../utils.js'
import config from '../config.js'

const jwtSign = util.promisify(jwt.sign)
const jwtVerify = util.promisify(jwt.verify)

const JWT_SECRET = config.auth.jwtSecret

export const sign = (id, options) => jwtSign({ id }, JWT_SECRET, options)
export const verify = (token) => jwtVerify(token, JWT_SECRET)

const auth = handleRejection(async (req, res, next) => {
  const authHeader = req.get('Authorization')
  if (!authHeader) {
    return next()
  }

  if (authHeader.startsWith('Bearer ')) {
    const token = authHeader.substring(7, authHeader.length)

    let userIdFromToken
    try {
      userIdFromToken = (await verify(token)).id
    } catch (error) {
      if (['TokenExpiredError', 'JsonWebTokenError', 'NotBeforeError'].includes(error.name)) {
        return res.status(401).send()
      } else {
        throw error
      }
    }

    const user = await prisma.user.findUnique({ where: { id: userIdFromToken } })
    if (!user) {
      return res.status(401).send()
    }

    const { password, ...userView } = user

    req.user = userView
  } else {
    return res.status(401).send()
  }

  next()
})

const SP = new SecurePassword()

export const hashPassword = async (password) => {
  const hashedPwdBuffer = await SP.hash(Buffer.from(password))
  return hashedPwdBuffer.toString("base64")
}

export const verifyPassword = async (hashedPassword, password) => {
  try {
    return await SP.verify(Buffer.from(password), Buffer.from(hashedPassword, "base64"))
  } catch (error) {
    console.error(error)
    return false
  }
}

And this is just a portion of the backend code (and for the username & password method only)! As you can see, we have quite a lot of flexibility here and get to do/specify things like:

  • choose the implementation method for auth (e.g. session or JWT-based)
  • choose the exact npm packages we want to use for the token (if going with JWT) and password management
  • parse the auth header and specify for each value (Authorization, Bearer, …) how to respond
  • choose the return code (e.g. 401, 403) for each possible outcome
  • choose how the password is decoded/encoded (base64)

On one hand, it’s really cool to have that level of control and flexibility in our code, but on the other hand, it’s quite a lot of decisions (== mistakes) to be made, especially for something as common as authentication!

If somebody later asks “so why exactly did you choose secure-password npm package, or why exactly base64 encoding?” it’s something we should probably answer with something else rather than “well, there was that SO post from 2012 that seemed pretty legit, it had almost 50 upvotes. Hmm, can’t find it now though. Plus, it has ‘secure’ in the name, that sounds good, right?”

Another thing to keep in mind is that we should also track how things change over time, and make sure that after a couple of years we’re still using the best practices and that the packages are regularly updated.

If we try to apply the principles from above (less code, less detailed instructions, stating what we want instead of how it needs to be done), the code for auth might look something like this: 

auth: {
    userEntity: User,
    externalAuthEntity: SocialLogin,
    methods: {
      usernameAndPassword: {},
      google: {}
    },
    onAuthFailedRedirectTo: "/login",
    onAuthSucceededRedirectTo: "/dashboard"
  }

Based on this, the computer/compiler could take care of all the stuff mentioned above, and then depending on the level of abstraction, provide some sort of interface (e.g. form components, or functions) to “hook” in with our own e.g. React/Node.js code (btw this is how it actually works in Wasp).

We don’t need to care what exact packages or encryption methods are used beneath the hood - it is the responsibility we trust with the authors and maintainers of the abstraction layer, just like we trust that Python knows the best how to sum two numbers on the assembly level and that it is kept in sync with the latest advancements in the field. The same happens when we rely on the built-in data structures or count on the garbage collector to manage our program’s memory well.

But my beautiful generated codez 😿💻! What happens with it then?​

Don’t worry, it’s all still here and you can generate all the code you wish! The main point to understand here is that ML code generation and framework/language development complement rather than replace each other and are here to stay, which is ultimately a huge win for the developer community - they will keep making our lives easier and allow us to do more fun stuff (instead of implementing auth or CRUD API for the n-th time)!

I see the evolution here as a cycle (or an upward spiral in fact, but that’s beyond my drawing capabilities):

  1. language/framework exists, is mainstream, and a lot of people use it
  2. patterns start emerging (e.g. implementing auth, or making an API call) → ML captures them, offers via autocomplete
  3. some of those patterns mature and become stable → candidates for abstraction
  4. new, more abstract, language/framework emerges
  5. back to step 1.

Language evolution lifecycle
It’s the circle of (language) life, and it moves us all - Ingonyama nengw' enamabala, …

Conclusion​

This means we are winning on both sides - when the language is mainstream we can benefit from ML code generation, helping us write the code faster. On the other hand, when the patterns of code we don’t want to repeat/deal with emerge and become stable we get a whole new language or framework that allows us to write even less code and care about fewer implementation details!

Fizz Buzz with Copilot - stop
The future is now, old man.

*Not to be biased, there are also other solutions offering similar functionality - e.g. TabNine, Webstorm has its own, Kite, GPT Code Clippy (OSS attempt) et al., but Github Copilot recently made the biggest splash.

Writing that informed this post​

Thanks to the reviewers​

Jeremy Howard, Maxi Contieri, Mario Kostelac, Vladimir Blagojevic, Ido Nov, Krystian Safjan, Favour Kelvin, Filip Sodic, Shayne Czyzewski and Martin Sosic - thank you for your generous comments, ideas and suggestions! You made this post better and made sure I don't go overboard with memes :).

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

ML code generation vs. coding by hand - what we think programming is going to look like

· 11 min read
Matija Sosic

We are working on a config language / DSL for building web apps that integrates with React & Node.js. A number of times we've been asked “Why are you bothering creating a new language for web app development? Isn’t Github Copilot* soon going to be generating all the code for developers anyhow?”.

This is on our take on the situation and what we think things might look like in the future.

Trending post!

This post was trending on HackerNews - you can see the discussion here.

Why (ML) code generation?​

In order to make development faster, we came up with IDE autocompletion - e.g. if you are using React and start typing componentDid, IDE will automatically offer to complete it to componentDidMount() or componentDidLoad(). Besides saving keystrokes, maybe even more valuable is being able to see what methods/properties are available to us within a current scope. IDE being aware of the project structure and code hierarchy also makes refactoring much easier.

Although that’s already great, how do we take it to the next level? Traditional IDE support is based on rules written by humans and if we e.g. wanted to make IDE capable of implementing common functions for us, there would be just too many of them to catalogize and maintain by hand.

If there was only a way for a computer to analyze all the code we’ve written so far and learn by itself how to autocomplete our code and what to do about humanity in general, instead of us doing all the hard work ...

Delicious and moist cake aside, we actually have this working! Thanks to the latest advances in machine learning, IDEs can now do some really cool things like proposing the full implementation of a function, based on its name and the accompanying comments:

Copilot example - text sentiment
GitHub Copilot generating a whole function body based on its signature and the comments on top of it.

This is pretty amazing! The example above is powered by Github Copilot - it’s essentially a neural network trained on a huge amount of publicly available code. I will not get into the technical details of how it works under the hood, but there are lots of great articles covering the science behind it.

Seeing this, questions arise - what does this mean for the future of programming? Is this just IDE autocompletion on steroids or something more? Do we need to keep bothering with manually writing code, if we can just type in the comments what we want and that’s it?

Who maintains the code once it’s generated?​

When thinking about how ML code generation affects the overall development process, there is one thing to consider that often doesn’t immediately spring to mind when looking at the impressive Copilot examples.

note

For the purposes of this post, I will not delve into the questions of code quality, security, legal & privacy issues, pricing, and others of similar character that are often brought up in these early days of ML code generation. Let’s just assume all this is sorted out and see what happens next.

The question is - what happens with the code once it is generated? Who is responsible for it and who will maintain and refactor it in the future?

Devs still need to maintain generated code

Although ML code generation helps with getting the initial code written, it cannot do much beyond that - if that code is to be maintained and changed in the future (and if anyone uses the product, it is), the developer still needs to fully own and understand it.

Imagine all we had was an assembly language, but IDE completion worked really well for it, and you could say “implement a function that sorts an array, ascending” and it would produce the required code perfectly. Would that still be something you’d like to return to in the future once you need to change your sort to descending 😅 ?

In other words, it means Copilot and similar solutions do not reduce the code complexity nor the amount of knowledge required to build features, they just help write the initial code faster, and bring the knowledge/examples closer to the code (which is really helpful). If a developer accepts the generated code blindly, they are just creating tech debt and pushing it forward.

Meet the big A - Abstraction 👆​

If Github Copilot and others cannot solve all our troubles of learning how to code and understanding in detail how session management via JWT works, what can?

Abstraction - that’s how programmers have been dealing with the code repetition and reducing complexity for decades - by creating libraries, frameworks, and languages. It is how we advanced from vanilla JS and direct DOM manipulation to jQuery and finally to UI libraries such as React and Vue.

Introducing abstractions inevitably means giving up on a certain amount of power and flexibility (e.g. when summing numbers in Python you don’t get to exactly specify which CPU registers are going to be used for it), but the point is that, if done right, you don’t need nor want such power in the majority of the cases.

Abstraction equals less responsibility
What Uncle Ben actually meant: avoiding responsibility is the main benefit of abstraction! (Peter totally missed the point, unfortunately, and became Spiderman instead of learning how to code)

The only way not to be responsible for a piece of code is that it doesn’t exist in the first place.

Because as soon as pixels on the screen change their color it’s something you have to worry about, and that is why the main benefit of all frameworks, languages, etc. is less code == less decisions == less responsibility.

The only way to have less code is to make less decisions and provide fewer details to the computer on how to do a certain task - ideally, we’d just state what we want and we wouldn’t even care about how it is done, as long as it’s within the time/memory/cost boundaries we have (so we might need to state those as well).

Let’s take a look at the very common (and everyone’s favorite) feature in the world of web apps - authentication (yaay ☠️ 🔫)! The typical code for it will look something like this:

Auth on the backend in Node.js - example
import jwt from 'jsonwebtoken'
import SecurePassword from 'secure-password'
import util from 'util'

import prisma from '../dbClient.js'
import { handleRejection } from '../utils.js'
import config from '../config.js'

const jwtSign = util.promisify(jwt.sign)
const jwtVerify = util.promisify(jwt.verify)

const JWT_SECRET = config.auth.jwtSecret

export const sign = (id, options) => jwtSign({ id }, JWT_SECRET, options)
export const verify = (token) => jwtVerify(token, JWT_SECRET)

const auth = handleRejection(async (req, res, next) => {
  const authHeader = req.get('Authorization')
  if (!authHeader) {
    return next()
  }

  if (authHeader.startsWith('Bearer ')) {
    const token = authHeader.substring(7, authHeader.length)

    let userIdFromToken
    try {
      userIdFromToken = (await verify(token)).id
    } catch (error) {
      if (['TokenExpiredError', 'JsonWebTokenError', 'NotBeforeError'].includes(error.name)) {
        return res.status(401).send()
      } else {
        throw error
      }
    }

    const user = await prisma.user.findUnique({ where: { id: userIdFromToken } })
    if (!user) {
      return res.status(401).send()
    }

    const { password, ...userView } = user

    req.user = userView
  } else {
    return res.status(401).send()
  }

  next()
})

const SP = new SecurePassword()

export const hashPassword = async (password) => {
  const hashedPwdBuffer = await SP.hash(Buffer.from(password))
  return hashedPwdBuffer.toString("base64")
}

export const verifyPassword = async (hashedPassword, password) => {
  try {
    return await SP.verify(Buffer.from(password), Buffer.from(hashedPassword, "base64"))
  } catch (error) {
    console.error(error)
    return false
  }
}

And this is just a portion of the backend code (and for the username & password method only)! As you can see, we have quite a lot of flexibility here and get to do/specify things like:

  • choose the implementation method for auth (e.g. session or JWT-based)
  • choose the exact npm packages we want to use for the token (if going with JWT) and password management
  • parse the auth header and specify for each value (Authorization, Bearer, …) how to respond
  • choose the return code (e.g. 401, 403) for each possible outcome
  • choose how the password is decoded/encoded (base64)

On one hand, it’s really cool to have that level of control and flexibility in our code, but on the other hand, it’s quite a lot of decisions (== mistakes) to be made, especially for something as common as authentication!

If somebody later asks “so why exactly did you choose secure-password npm package, or why exactly base64 encoding?” it’s something we should probably answer with something else rather than “well, there was that SO post from 2012 that seemed pretty legit, it had almost 50 upvotes. Hmm, can’t find it now though. Plus, it has ‘secure’ in the name, that sounds good, right?”

Another thing to keep in mind is that we should also track how things change over time, and make sure that after a couple of years we’re still using the best practices and that the packages are regularly updated.

If we try to apply the principles from above (less code, less detailed instructions, stating what we want instead of how it needs to be done), the code for auth might look something like this: 

auth: {
    userEntity: User,
    externalAuthEntity: SocialLogin,
    methods: {
      usernameAndPassword: {},
      google: {}
    },
    onAuthFailedRedirectTo: "/login",
    onAuthSucceededRedirectTo: "/dashboard"
  }

Based on this, the computer/compiler could take care of all the stuff mentioned above, and then depending on the level of abstraction, provide some sort of interface (e.g. form components, or functions) to “hook” in with our own e.g. React/Node.js code (btw this is how it actually works in Wasp).

We don’t need to care what exact packages or encryption methods are used beneath the hood - it is the responsibility we trust with the authors and maintainers of the abstraction layer, just like we trust that Python knows the best how to sum two numbers on the assembly level and that it is kept in sync with the latest advancements in the field. The same happens when we rely on the built-in data structures or count on the garbage collector to manage our program’s memory well.

But my beautiful generated codez 😿💻! What happens with it then?​

Don’t worry, it’s all still here and you can generate all the code you wish! The main point to understand here is that ML code generation and framework/language development complement rather than replace each other and are here to stay, which is ultimately a huge win for the developer community - they will keep making our lives easier and allow us to do more fun stuff (instead of implementing auth or CRUD API for the n-th time)!

I see the evolution here as a cycle (or an upward spiral in fact, but that’s beyond my drawing capabilities):

  1. language/framework exists, is mainstream, and a lot of people use it
  2. patterns start emerging (e.g. implementing auth, or making an API call) → ML captures them, offers via autocomplete
  3. some of those patterns mature and become stable → candidates for abstraction
  4. new, more abstract, language/framework emerges
  5. back to step 1.

Language evolution lifecycle
It’s the circle of (language) life, and it moves us all - Ingonyama nengw' enamabala, …

Conclusion​

This means we are winning on both sides - when the language is mainstream we can benefit from ML code generation, helping us write the code faster. On the other hand, when the patterns of code we don’t want to repeat/deal with emerge and become stable we get a whole new language or framework that allows us to write even less code and care about fewer implementation details!

Fizz Buzz with Copilot - stop
The future is now, old man.

*Not to be biased, there are also other solutions offering similar functionality - e.g. TabNine, Webstorm has its own, Kite, GPT Code Clippy (OSS attempt) et al., but Github Copilot recently made the biggest splash.

Writing that informed this post​

Thanks to the reviewers​

Jeremy Howard, Maxi Contieri, Mario Kostelac, Vladimir Blagojevic, Ido Nov, Krystian Safjan, Favour Kelvin, Filip Sodic, Shayne Czyzewski and Martin Sosic - thank you for your generous comments, ideas and suggestions! You made this post better and made sure I don't go overboard with memes :).

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/08/15/how-to-communicate-why-your-startup-is-worth-joining.html b/blog/2022/08/15/how-to-communicate-why-your-startup-is-worth-joining.html index 4df9b0e57c..df8936231d 100644 --- a/blog/2022/08/15/how-to-communicate-why-your-startup-is-worth-joining.html +++ b/blog/2022/08/15/how-to-communicate-why-your-startup-is-worth-joining.html @@ -19,13 +19,13 @@ - - + + -
-

How to communicate why your startup is worth joining

· 31 min read
Vasili Shynkarenka

Except for a handful of companies who send people to Mars or develop AGI, most startups don’t seem to offer a good reason to join them. You go to their websites and all you see is vague, baseless, overly generic mission-schmission/values-schvalues HR nonsense that supposedly should turn you into a raving fan of whatever they’re doing and make you hit that “Join” button until their servers crash. Well…

Some people think that’s because most startups aren’t worth joining. I disagree. This argument generalizes one’s own reasons for joining a startup onto every other human being out there, which is unlikely to be true. I think most startups, no matter how ordinary, do have a reason to join them; a good reason; even many good reasons — they just fail to communicate them well. They’re like a shy nerd on Tinder with an empty bio and no profile pic: a kind, intelligent, and thoughtful human being who, unfortunately, will be ruthlessly swiped left — not because he’s a bad match but because his profile doesn’t show why he’s a good one.

Visually, this “Tinder profile problem” looks like this:

Illustration of candidates not seeing why to join a startup

Now, look what would happen if a startup communicated a bit better. Suddenly, our candidates could see a reason to join. If the reason is good, they might even swipe right.

Illustration of candidates seeing one reason to join a startup

But most startups have many good reasons to join them. If only they communicated well, the outcome would be something like this:

Illustration of candidates seeing many reasons to join; one candidate already running for it

Now, you’re probably wondering just what exactly those reasons are.

Here’s a rough list:

  1. The founders are interesting / fun / smart / human / you name it
  2. The team is great
  3. The culture is amazing
  4. The business is doing well

However, if you just copy this list and paste it on your jobs page, you will accomplish nothing. The candidates will never believe you. What you need to do instead is to supply them with a system of concretes (facts) from which their minds will form these abstract conclusions.

For example:

  • Instead of declaring that “the founders are reflective, thoughtful, and persistent,” show them how so, like Sarah from Canny does by writing comprehensive year-in-review blog posts for four years in a row.
  • Instead of proclaiming that “the founders are humble and can have fun,” show them how so, like Michael from Fibery did by becoming a hero of this hilarious page. (No businessy founder would ever agree to make this public. Michael did.)
  • Instead of purporting that “the team is great” or “you’ll work alongside very smart people” (God, I hate that one!), show them who exactly those people are, as PostHog does here and Wasp does here and here.

In the rest of the post, I’ll go through the four broad reasons to join a startup one by one and show real-life examples of communicating them well. In the end, I will explain how these four reasons, communicated well, fuse into two compelling messages that will interest any candidate.

One last thing. For the sake of clarity and comprehension, I will write in the second person. Instead of saying “candidates would never believe them,” I will say “you would never believe them.” It’s much easier to read and understand.

Possible reasons why your startup is worth joining, and how to communicate them well​

1. FOUNDERS — or, the founders are interesting / fun / smart / human / you name it​

Most startups have curious, interesting, ambitious, terribly smart founders; the kind most of us would love to work for if we had a chance. Sadly, only a few leverage this asset. In most cases, all you get is a small round pic with a fancy title and a few abstract, high-level sentences that cause no excitement whatsoever. What a shame!

How Canny commmunicates who their founders are​

Founder Stories blog category​

The first notable thing Canny does is the Founder Stories category in their blog. By quickly skimming the posts, you can understand that Sarah and Andrew (the founders):

If they just pinned this list of virtues to their Jobs page, you would never believe them. Instead, Sarah and Andrew show what actions they take, how they work, how they think, how they live — and you make up their own mind about what kind of people Sarah and Andrew are from seeing all that. The difference is enormous.

Note their writing style. They don’t claim to be know-it-alls with titles like “How to bootstrap your startup.” Instead, they write “How we Bootstrapped our SaaS Startup to Ramen Profitability.” They cover only what they know instead of overgeneralizing. This shows both expertise and humility.

A screenshot of Canny's Founder Stories blog category

Personal Instagram​

The second thing Sarah and Andrew do well to communicate who they are is their Instagram. They don’t post glamorous keynote appearances, as many entrepreneurs do. They share the actual day-to-day working life — both the fun and the struggle. It gives you a good idea of what they’re after in life. (Not keynotes.) That’s why it works, and that’s why people love it.

A photo from Sarah and Andrew's personal Instagram

Side note: Sarah explains how she develops the Canny brand in this post. If you want to build a good one, give it a read. She also wrote about how they attract top talent. You can read it here.

How Fibery communicates who their founder is​

Startup Diary blog post series​

While you can get a pretty good idea of Michael (the founder) from the hilarious “Remote” page Fibery shipped last year, his Startup Diary post series offers an even better insight into his soul. In these monthly posts, Michael honestly shares everything that’s going on with Fibery, including the good, the bad, and the ugly: firing people for poor performance, losing important customers, and failing to reach product-market fit. The fact that he’s already written 45 of those (as of Aug 2022) is also telling. And he’s not a native English speaker. If he can do that, why can’t you?

A screenshot of Fibery's Startup Diary blog category

Crazy challenges​

Besides writing the Startup Diary, Michael also embarks on crazy challenges like writing 100 posts about products. Only a passionate, driven person would commit to such a thing. You cannot help but respect him for it. (Before this challenge, he wrote 100 Medium posts in 100 days in 2018. You can read them here. Just scroll a few screens to reach the old stuff.)

A screenshot of Fibery's 100 posts about products blog category

If you look carefully, you’ll notice that Michael’s thinking about building a company is different from Sarah’s. For example, he despises the gentle, soothing “Oh don’t worry that it didn’t work out; you did such a good work!” approach, which is ubiquitous in the modern startup world. Instead, he states that dissatisfaction leads to progress, referring to the famous “Not quite my tempo” scene from Whiplash. Does that make you like him more than Sarah?

It depends. If you believe that being soft and balanced is better, you’ll go with Sarah; if you believe that real progress comes only from working yourself to the bone, you’ll go with Michael (or Elon). The important thing is that both founders have their own, unique viewpoints of how things should be done, and that they communicate these viewpoints as-is instead of chopping their legs off to fit the latest Procrustean fad.

In-depth, original blog posts about the industry​

Some entrepreneurs say that doing a startup is like “jumping off a cliff and building your wings on the way down.” Some of it might be true. But if you want reasonable people to jump with you, you better tell them that you have a degree in engineering and know how to assemble wings in a free fall. Otherwise, the only team you’ll recruit is a suicide squad looking for a splashy hit.

To communicate his expertise, Michael writes in-depth, original, theoretical posts about the nature of knowledge management and organizational productivity. These posts are gems, both literally and metaphorically. (They’re filed under the Gems category in the Fibery blog.)

For example:

After reading these articles, you understand not only that Michael really knows how to build wings while falling off the cliff, but that he has already jumped a few times. (Prior to Fibery, Michael had worked on knowledge management for more than a decade. He also had built a successful project management software, Targetprocess.) You know that he’s an expert who can be trusted.

Interestingly, even though Michael writes differently from Sarah, they both leverage what they’re good at. Sarah does not try to produce treatises on software development philosophy, and Michael doesn’t gush out with his personal learnings from building a startup. That, I think, is the right way to do it.

How PostHog communicates who their founders are​

PostHog’s founders James and Tim don’t write 100 posts in 100 days or run a personal Instagram. But they’ve come up with something else to communicate what kind of people they are. And it’s something unique.

Well-written, concise bio​

First, both founders have decent profiles in the company handbook. These bios are short, clear, and humane. They’re also very specific. Where else have you seen the name of the CEO’s cat?

A screenshot of James Hawkins' bio in the PostHog Handbook

Personal README files​

Second, both James and Tim have an extensive README file (one, two) on how to work with them. These files give you an insight into their productivity habits, interests, and quirks. In fact, after reading them, you will likely have a better idea of the founders than you’d usually get from working at a company for a month!

For instance, James’s file has sections like:

  • Short bio. Includes very specific details like: “I tend to work 9am to 5pm with an hour for lunch, then I have a gap to have dinner with my family, then 9pm to around 11pm ish.”
  • Very clear areas of responsibility. No need to wonder what the hell the CEO is doing anymore!
  • Quirks. These are remarkably humble and open-minded, like:
    • “If I haven’t responded to something that you’ve sent me, that’s probably because I’ve read it and don’t feel particularly strongly - so just make a call on what to do if you don’t hear back in a reasonable time frame.”
    • “I’m a little disorganized. I compensate for this by making sure the teams I work on have this skill. Often I think this actually helps me prioritize the things that really matter.”
    • Explaining these quirks is an ingenious move. Besides explaining how to work with James, this section communicates that he’s profoundly self-aware and willing to accept and leverage his weaknesses. These qualities are very rare and incredibly valuable.
  • What I value. In stark contrast to most HR nonsense, these values are very clear, very specific, and written in English rather than HRese. (I just came up with this term: it means “legalese but for HR.”) Here are two examples:
    • “Proactivity. Do not ask me for permission to do things - I wouldn’t have hired you if I didn’t trust you. I’d rather 9 things get done well and 1 thing I disagree with than we don’t get anything done at all.”
    • “Directness impresses me. If you don’t like something please just say so. It makes for much healthier relationships.”

In addition to that, there’s also: How I can help you, How you can help me, My goals until end December 2022 (very specific!), Personal strategy, Execution todo (including “1 bike ride a week”!) and Archived todo.

In summary, this README page is a gem. I wish more founders had them.

A screenshot of James Hawkins' README in the PostHog Handbook

How we at Wasp communicate who our founders are​

“Who we are” section of every job description page​

Matija and Martin (the founders of Wasp) embedded a concise description of who they are right into each job description page in Notion. They knew that this is the first company artifact many candidates will see. So they saved candidates time and effort on digging up who the hell started Wasp.

Note the language and substance of this list. When you read it, you immediately get a sense of who Matija and Martin are as people — fun, easygoing, no-corporate-bullshit kinda guys. Now imagine it said something “more normal,” like: “The company was founded by seasoned entrepreneurs…” What impression would that make?

A screenshot of Wasp's job description page

2. TEAM — or, the team is great​

It is startling how little most startups tell you about their teams. Often all you get is a chessboard of faces and titles, which gives you no idea who these people are as people or how working with them will feel like. Given how crucial a reason “great team” is for most candidates, improving how you communicate it seems like a low-hanging fruit.

How Canny communicates who is on their team​

Decent team page​

The Canny’s difference starts with a team page. It has a dense summary of who each team member is as a person and includes high-quality, lively photos of everybody.

A screenshot of Canny's Team page

Look how specific those bios are. In most cases, all you get here is a generic “developer” or “marketer” without any personal details. Bios of robots, not people. No wonder nothing comes to mind, except perhaps for Agent Smith. But Canny’s bios are different. When you read them, you can actually imagine the person! They’re Neos in the world of Smiths.

Remarkable “Why work at Canny” blog post​

From there, it gets only better. Canny’s chief weapon for explaining their team is a blog post, the “Why work at Canny” blog post. Sarah wrote it back in the summer of 2021. It is full of quotes from team members and photos of their workdays and vacations. Real photos of real people. No wonder the comments section under the post abounds with raving fans willing to join the team straight away!

A screenshot of comments under the Canny's Why work at Canny blog post

Perhaps the best thing about this post is how little work it takes to create one. I imagine that collecting the data took some time, but the actual writing (it’s an 11-min read) took no more than a week. A week of work for a candidate magnet of such tremendous power? Sounds like a deal.

P.s. Sarah writes a lot more about their team in her yearly review posts, but I decided not to elaborate on those for the sake of clarity. You can check them out here: year 1, year 2, year 3, and year 4.

How Fibery communicates who is on their team​

Weird About Us page​

Unlike Canny and PostHog’s, Fibery’s About Us page doesn’t reveal much info about each team member. You will find no bios or README files there. But it clearly tells you one thing: the team is a bunch of weirdos. So, if weird is your thing, you’ll be attracted to Fibery like a moth to a flame. (Side note: Fibery managed to clearly explain their vision in one paragraph. This is rare.)

A screenshot of Fibery's About Us page

I’ve already mentioned Michael’s Startup Diary monthly blog series. What I didn’t say is that each post communicates something about the team: who did what that month, random Slack posts (links, quotes, tweets, and images), etc. If someone new joined that month, Michael writes a few paragraphs explaining who that person is, where they come from, what they’re going to do at Fibery, and even attaches a photo. Like Chris.

A screenshot of Fibery's Startup Diary blog post

How PostHog communicates who is on their team​

Team section in the company handbook​

At PostHog, every team member has a well-written, few-paragraphs-long bio and a stylish illustration on the Team section of the PostHog’s Handbook. (Which is a work of art worthy of its own blog post, by the way.) Many team members have their own README files, like the founders do. Check out Lottie Coxon’s, PostHog’s Graphic Designer’s README here, and some others here and here. Even a quick read through these bios and READMEs gives you a good idea of who PostHog has on board.

A screenshot of PostHog's team section in the handbook

Another screenshot of PostHog's team section in the handbook

Day-in-life videos from employees​

In addition to bios and READMEs, PostHog has a day-in-life video of Lottie, their graphic designer. It communicates a lot more information about what kind of person she is and how working at PostHog feels like than her bio. I wish they had more of those.

A screenshot from PostHog's graphic designer day-in-life video

Finally, PostHog’s handbook offers two more sections where candidates can learn even more about the team: Culture and Team structure. All are worth a read, and each tells you something new about the company and the team, nurturing your liking and respect for these people. Definitely worth stealing.

How we at Wasp communicate who is on our team​

“Meet the team” blog posts​

To help candidates understand who they will be working with, we at Wasp write a blog post about each new hire:

The posts are brief enough to be read in one sitting. Yet, they are very informative. Basically, each post is an interview, presented as an article. We hope they give candidates a good idea of who they'll be spending half of their waking time with.

A screenshot of Wasp's Meet the team blog post

3. CULTURE — or, the culture is amazing​

While researchers still argue about the ultimate definition, most of us understand culture as “what working here feels like” and/or “how we do things here.” We also understand how crucial it is for those looking for work. It seems glaringly obvious that startups should work hard on communicating their culture. Yet, most companies don’t. Or, even worse, they flood their websites with meaningless HR fluff, which only scares interesting people away. In short, communicating culture well is another low-hanging fruit waiting to be picked.

How Canny communicates their culture​

Canny does an outstanding job at communicating their culture. The primary tool they employ is, once again, their blog. (Note how multifunctional it is: founders, expertise, team, and now culture.) The posts in the Founder Stories category convey very well what working at Canny feels like. Here are a few examples.

“Why work at Canny” blog post​

I’ll risk repeating myself, but this post so beautifully explains Canny’s culture that I couldn’t resist. It mentions why and how they work remotely, how they do team retreats (with photos and a video from Lisbon!), and how they had fun together playing weird Zoom games when travel was not an option due to Covid.

Pay attention to the imagery. It communicates a lot more information than any lengthy, elaborate description would. Indeed, a picture is often worth a thousand words.

A photo of Canny's two team members hacking in Denver

“Lessons from a year of team retreats” blog post​

Instead of saying that “team is our priority” or “we invest in our people,” Sarah shows what they’ve done to support their team.

Again, note how specific the imagery is.

A photo from Canny's Lessons from a year of team retreats blog post

Interestingly, Sarah’s post isn’t framed as “hey we do many team retreats, we’re awesome, come work for us.” If they wrote that, the reader would feel uneasy. They would sense bragging. That’s why the explicit message in the post is what Canny learned doing team retreats, not that they’ve done many. This explicit message, however, implies that they indeed have done many retreats! It sends a message that Canny cares for their employees without explicitly saying so. This is what true mastery looks like.

“The end of our digital nomad journey” blog post​

Although this post describes Sarah and Andrew’s personal nomad experience, Sarah managed to reveal Canny’s culture through it. To do that, she described how the team worked on Canny during those nomad years. She also wrote about their communication struggles, routines, and a lot more. And, again, look at how effectively her seemingly imperfect screenshots and photos transmit the vibe!

A photo from Canny's The end of our digital nomad journey blog post

Another photo from Canny's The end of our digital nomad journey blog post

How Fibery communicates their culture​

While Fibery’s culture is different from Canny’s, they also communicate it well. Their primary tool is a weird, quirky website full of special projects that give you a sense of how they do things at Fibery and what working there feels like.

Anxiety page​

The first project is Fibery’s /anxiety page. Launched in 2019, it mocks every serious enterprise software out there with puns like “Yet another collaboration tool” as the page title, “Mistake” as a sign-up button text, and, my favorite, “Try—Suffer—Quit” page structure.

A screenshot of Fibery's /anxiety page

One day three years ago, someone submitted this page to Hacker News. The post surged to the top of the frontpage, stayed there for many hours, and got 705 upvotes and 145 comments from people all over the world relating to Fibery’s culture. Why? Because it felt real.

Here’s a glimpse of what people wrote in the comments:

A screenshot of Hacker News comments on Fibery's /anxiety page

Another screenshot of Hacker News comments on Fibery's /anxiety page

Remote page​

The second special project Fibery did to communicate their culture is the /remote page. It shows what working from home is really like. It’s the funniest thing I’ve ever seen done by a software startup. (Have you ever seen a CEO being licked by a dog?) It also shows how the Fibery team works and even how they use Fibery to build Fibery. Like Canny’s “Lessons from a year of team retreats” blog post, it does so implicitly. A true masterpiece.

Weird, humorous site​

Broadly, the whole site screams that Fibery is a place for misfits, rebels, and trouble makers; the place where such people will be valued and will feel like home; the place built around brutal honesty and spicy humor.

The “What (non-)customers say” section is worth a mention. Over my nine years in startups, I haven’t seen a site that a) lists bad customer reviews; and b) uses 💩 emoji as a filter. Again, this is telling. It says a lot about who they are as people: humble, real, and fond of humor.

A screenshot of Fibery's About Us page, What non-customers say section

How PostHog communicates their culture​

Comprehensive company handbook covering all-things culture​

PostHog’s way of communicating their culture is the most explicit of all four examples, yet very effective. Their primary tool is the PostHog Handbook, which covers virtually every aspect of what working at PostHog feels like: interviews, onboarding, training, management, communication, and even firing. (They call it offboarding.)

The handbook goes all the way up to the high-level strategy, which is very clear. Notably, PostHog’s strategy section not only puts forth ambitious goals but actually explains how exactly the company will get there.

The values section is very specific; perhaps the most specific I’ve ever seen. PostHog does not merely list their values as meaningless abstractions but supports them with evidence. Some values have many paragraphs of examples demonstrating how the team follows them.

A screenshot of the Values section in the PostHog's handbook

They also have a specific Culture page with a 5-minute video from the CEO explaining how they designed PostHog for remote work from day one, which nicely complements the text.

A screenshot from James Hawkins's video

In summary, if Canny’s weapon of choice is the blog and Fibery’s is the website, then PostHog’s is definitely the handbook. It’s a work of art.

How we at Wasp communicate our culture​

Easygoing vibe from memes, copy, and imagery​

Unlike Posthog, we at Wasp don’t (yet) have a dedicated Culture page. We are too small for that. But that doesn’t stop us from showing what working at Wasp feels like. We just use different tools.

Our Twitter, blog, and monthly updates abound with memes, GIFs, and hilarious imagery. Plus, we write them in a humorous, lighthearted, easygoing style. By just scrolling through these things for a few minutes, candidates can understand that we aren’t some corporate bros. And if they like working on interesting things while having fun, they won’t help but feel an inkling to reach out.

A funny image from Wasp's blog post about GitHub Copilot

A photo of Wasp's team packing t-shirts for users

4. PROGRESS — or, the business is doing well​

When you just closed an $80 million Series B or signed Facebook as a customer, communicating progress is easy. You just state these facts. However, most companies need to attract great people way before Series B. In fact, it is these very people who’re going to get you there. As most startups are secretive about how things are going, communicating that things are going somehow — no matter how negligible your progress in contrast to the big guys — becomes quite an advantage. It immediately de-risks the opportunity in the candidate’s eyes. So, if EXPERTISE is about convincing candidates that you know how to build the wings, PROGRESS is about showing them the half-built carcass on your way down. Both are important if you want great people to jump off the cliff with you.

How Canny communicates their progress​

To give candidates a sense that things are moving, that this company is not some long slog but a place where progress is made every day, that they can become a part of something that’s growing and, therefore, can grow themselves, to do all that, Canny does two things.

“Year in review” blog posts​

The first one is their “Year in review” blog post series. Such comprehensive, thoughtful reviews are rare in the startup world. What is even rarer is when these posts span over four consecutive years. It sends a message that the founders are persistent and devoted to making this company successful.

Below are all Canny’s year-in-review posts in a sequential order:

A screenshot of Canny's Year in review blog post

Important revenue milestones blog posts​

In addition to year-in-review posts, Sarah writes about hitting notable revenue milestones. Like with yearly reviews, such transparency is rare. It attracts attention, causes liking, and builds trust.

For example:

A screenshot of Canny's How we built a $1m ARR SaaS startup blog post

Short tweets with progress summary​

Finally, Sarah occasionally tweets short summaries of their progress, like this one. These tweets work like ads. Over time, a candidate’s brain fuses them into a broader idea like “Canny is growing” or “Canny is doing well.” Then, once a candidate decides to change jobs, it nudges the candidate to consider Canny.

A screenshot of Sarah’s tweet with progress update

How Fibery communicates their progress​

Startup Diary blog posts​

The most notable thing Fibery does to communicate their progress is the Startup Diary blog posts series written by the founder, Michael, every month, for the past 45 months. It’s the longest series of monthly updates I know. In these posts, Michael honestly shares everything that’s going on with the company: the good, the bad, and the ugly.

Below are just a few examples, selected by me. You can study all Fibery’s monthly updates here.

  • #2 Slow September 2018 — Fibery startup progress in September 2018. Slow month with not so many news. First positive feedback. Company name selection.
  • #6 Planning Private Beta in January 2019 — Fibery startup progress in January 2019: Private beta goals, selecting a market positioning (hard), apps re-design.
  • #10 Burn in May 2019 — Several people burned out, new features are delivered, public release will be sooner (we hope) (despite ill fortune).
  • #16 Crazy November 2019 — Fibery 1.0 is silently launched. Silence is hard to keep. HackerNews front page. Twitter madness. 3000 registered accounts.
  • #17 Fragmented December 2019 — Public announcements moved to January. +Lena. Tons of feedback. First money! Hype is over. We consider rising a ~$4M round.
  • #35 Raised $3.1M in July 2021 — TLDR: We closed $3.1M seed round. Building a second brain for teams. Fibery mission. Building in Public. Automation rules. Documents and Rich Text history.
  • #36 20k MRR in August 2021 — Special Startup Diary edition. 20k MRR & 15 new customers! +Chris. +Sales agency. 4 case studies. Airtable integration & notify people action.
  • ($30K MRR) #42 Connecting the dots in April 2022 — TLDR: 🇺🇦 Ukrainian war affected our performance. $30K MRR 🐌. 69 reviews in G2 ❤️. Marketing for customer-built products is hard 🥉. 12 customer stories 👻. 2 hours downtime 🥲. New navigation ⛵️. My Space 🔒.

Imagine a candidate who is considering two or more similar startups. Guess what might convince them to go with Fibery? Progress. Or, more exactly, an understanding that Fibery is persistently making progress and, therefore, has a decent chance to become successful. Delivered through these very updates.

Last year, Michael (Fibery’s CEO) started writing year-in-review posts too. I didn’t mention them because there’s just one post for now. You can read his 2021 review here.

Open Startup page with metrics​

The second tool that Fibery employs to share their progress is the /open-startup page. Like monthly updates, it gives candidates a good idea of how the business is doing. This understanding, however, comes from a different source: pure numbers. And numbers often speak louder than words.

A screenshot of Fibery's Open startup page

How PostHog communicates their progress​

Story page in the handbook​

In the PostHog’s handbook, they have a page called Story. It succinctly shows the milestones the company has hit so far. For each milestone, they offer a clear and concise explanation of what happened, sometimes no longer than a sentence. As a result, candidates can get a good idea of how things are going in less than a minute. That’s something to aspire to.

Here’s the section titles:

  • Jan 2020: The start
  • Feb 2020: Launch
  • Apr 2020: $3M Seed round
  • May 2020: First 1,000 users
  • Oct 2020: Billions of events supported
  • Nov 2020: Building a platform
  • Dec 2020: $9M Series A
  • Jun 2021: $15M Series B
  • Sep 2021: Product Market fit achieved for PostHog Scale

A screenshot of PostHog's Story page

How we at Wasp communicate our progress​

Blog posts covering big milestones (YC, $1.5m seed)​

For each milestone, Matija and Martin (Wasp founders) write a blog post describing not only what they accomplished but also how they did it.

For example, when Wasp got into YC, they didn’t just post the news on Twitter. They wrote a blog about their journey to Y Combinator. It got thousands of views.

Same with fundraising. When Wasp closed a $1.5m seed, Matija documented and shared their fundraising learnings in a blog post. It ended up on the HN frontpage. (Incidentally, this post communicates something important about the founders. It takes persistence to run 250+ meetings in 98 days.)

A screenshot of Wasp's fundraising learnings blog post

Monthly newsletter with updates​

To keep the momentum, Matija also writes a monthly newsletter. It’s similar to Michael’s Startup Diary in substance, but has a different style. Wasp style. (Which, again, communicates our culture.)

Like PostHog’s Story page, Wasp’s monthly updates give candidates a bird’s eye view over everything that’s happened in the past two years. To anyone interested in connecting the dots, this page is a gem.

A screenshot of Wasp's monthly newsletter archives

So, why should people join your startup?​

The founders are interesting / fun / smart / human / you name it

The team is great

The culture is amazing

The business is doing well

By communicating all these reasons well, what Canny, Fibery, PostHog, and (we hope!) Wasp really end up transmitting is two powerful messages:

  • The company is likely to succeed
  • Working there will be awesome

These two messages are the real answer to “why people should join your company.” The trick, however, and the reason why I wrote this post, is that you can only transmit them indirectly. You can’t say “our founders are great.” You need to provide candidates with many-many facts about the founders, which their minds will then fuse into this abstract conclusion. Ditto for expertise, team, culture, and progress. Eventually, these first-level abstractions will blend into still broader ones: “the company is likely to succeed” and “working there will be awesome.”

Thus, there’s no single, ultimate answer to “why people should join your company.” There’s only a complex system of concrete, specific units of information from which candidates make the answer themselves. In other words, you can’t teach them why your company is likely to succeed and why working here will be awesome. But you can outline the facts and let them learn for themselves. I hope this post shows how to do that outlining well, and I hope you will apply this knowledge to bring talented people onboard and build great things.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

How to communicate why your startup is worth joining

· 31 min read
Vasili Shynkarenka

Except for a handful of companies who send people to Mars or develop AGI, most startups don’t seem to offer a good reason to join them. You go to their websites and all you see is vague, baseless, overly generic mission-schmission/values-schvalues HR nonsense that supposedly should turn you into a raving fan of whatever they’re doing and make you hit that “Join” button until their servers crash. Well…

Some people think that’s because most startups aren’t worth joining. I disagree. This argument generalizes one’s own reasons for joining a startup onto every other human being out there, which is unlikely to be true. I think most startups, no matter how ordinary, do have a reason to join them; a good reason; even many good reasons — they just fail to communicate them well. They’re like a shy nerd on Tinder with an empty bio and no profile pic: a kind, intelligent, and thoughtful human being who, unfortunately, will be ruthlessly swiped left — not because he’s a bad match but because his profile doesn’t show why he’s a good one.

Visually, this “Tinder profile problem” looks like this:

Illustration of candidates not seeing why to join a startup

Now, look what would happen if a startup communicated a bit better. Suddenly, our candidates could see a reason to join. If the reason is good, they might even swipe right.

Illustration of candidates seeing one reason to join a startup

But most startups have many good reasons to join them. If only they communicated well, the outcome would be something like this:

Illustration of candidates seeing many reasons to join; one candidate already running for it

Now, you’re probably wondering just what exactly those reasons are.

Here’s a rough list:

  1. The founders are interesting / fun / smart / human / you name it
  2. The team is great
  3. The culture is amazing
  4. The business is doing well

However, if you just copy this list and paste it on your jobs page, you will accomplish nothing. The candidates will never believe you. What you need to do instead is to supply them with a system of concretes (facts) from which their minds will form these abstract conclusions.

For example:

  • Instead of declaring that “the founders are reflective, thoughtful, and persistent,” show them how so, like Sarah from Canny does by writing comprehensive year-in-review blog posts for four years in a row.
  • Instead of proclaiming that “the founders are humble and can have fun,” show them how so, like Michael from Fibery did by becoming a hero of this hilarious page. (No businessy founder would ever agree to make this public. Michael did.)
  • Instead of purporting that “the team is great” or “you’ll work alongside very smart people” (God, I hate that one!), show them who exactly those people are, as PostHog does here and Wasp does here and here.

In the rest of the post, I’ll go through the four broad reasons to join a startup one by one and show real-life examples of communicating them well. In the end, I will explain how these four reasons, communicated well, fuse into two compelling messages that will interest any candidate.

One last thing. For the sake of clarity and comprehension, I will write in the second person. Instead of saying “candidates would never believe them,” I will say “you would never believe them.” It’s much easier to read and understand.

Possible reasons why your startup is worth joining, and how to communicate them well​

1. FOUNDERS — or, the founders are interesting / fun / smart / human / you name it​

Most startups have curious, interesting, ambitious, terribly smart founders; the kind most of us would love to work for if we had a chance. Sadly, only a few leverage this asset. In most cases, all you get is a small round pic with a fancy title and a few abstract, high-level sentences that cause no excitement whatsoever. What a shame!

How Canny commmunicates who their founders are​

Founder Stories blog category​

The first notable thing Canny does is the Founder Stories category in their blog. By quickly skimming the posts, you can understand that Sarah and Andrew (the founders):

If they just pinned this list of virtues to their Jobs page, you would never believe them. Instead, Sarah and Andrew show what actions they take, how they work, how they think, how they live — and you make up their own mind about what kind of people Sarah and Andrew are from seeing all that. The difference is enormous.

Note their writing style. They don’t claim to be know-it-alls with titles like “How to bootstrap your startup.” Instead, they write “How we Bootstrapped our SaaS Startup to Ramen Profitability.” They cover only what they know instead of overgeneralizing. This shows both expertise and humility.

A screenshot of Canny's Founder Stories blog category

Personal Instagram​

The second thing Sarah and Andrew do well to communicate who they are is their Instagram. They don’t post glamorous keynote appearances, as many entrepreneurs do. They share the actual day-to-day working life — both the fun and the struggle. It gives you a good idea of what they’re after in life. (Not keynotes.) That’s why it works, and that’s why people love it.

A photo from Sarah and Andrew's personal Instagram

Side note: Sarah explains how she develops the Canny brand in this post. If you want to build a good one, give it a read. She also wrote about how they attract top talent. You can read it here.

How Fibery communicates who their founder is​

Startup Diary blog post series​

While you can get a pretty good idea of Michael (the founder) from the hilarious “Remote” page Fibery shipped last year, his Startup Diary post series offers an even better insight into his soul. In these monthly posts, Michael honestly shares everything that’s going on with Fibery, including the good, the bad, and the ugly: firing people for poor performance, losing important customers, and failing to reach product-market fit. The fact that he’s already written 45 of those (as of Aug 2022) is also telling. And he’s not a native English speaker. If he can do that, why can’t you?

A screenshot of Fibery's Startup Diary blog category

Crazy challenges​

Besides writing the Startup Diary, Michael also embarks on crazy challenges like writing 100 posts about products. Only a passionate, driven person would commit to such a thing. You cannot help but respect him for it. (Before this challenge, he wrote 100 Medium posts in 100 days in 2018. You can read them here. Just scroll a few screens to reach the old stuff.)

A screenshot of Fibery's 100 posts about products blog category

If you look carefully, you’ll notice that Michael’s thinking about building a company is different from Sarah’s. For example, he despises the gentle, soothing “Oh don’t worry that it didn’t work out; you did such a good work!” approach, which is ubiquitous in the modern startup world. Instead, he states that dissatisfaction leads to progress, referring to the famous “Not quite my tempo” scene from Whiplash. Does that make you like him more than Sarah?

It depends. If you believe that being soft and balanced is better, you’ll go with Sarah; if you believe that real progress comes only from working yourself to the bone, you’ll go with Michael (or Elon). The important thing is that both founders have their own, unique viewpoints of how things should be done, and that they communicate these viewpoints as-is instead of chopping their legs off to fit the latest Procrustean fad.

In-depth, original blog posts about the industry​

Some entrepreneurs say that doing a startup is like “jumping off a cliff and building your wings on the way down.” Some of it might be true. But if you want reasonable people to jump with you, you better tell them that you have a degree in engineering and know how to assemble wings in a free fall. Otherwise, the only team you’ll recruit is a suicide squad looking for a splashy hit.

To communicate his expertise, Michael writes in-depth, original, theoretical posts about the nature of knowledge management and organizational productivity. These posts are gems, both literally and metaphorically. (They’re filed under the Gems category in the Fibery blog.)

For example:

After reading these articles, you understand not only that Michael really knows how to build wings while falling off the cliff, but that he has already jumped a few times. (Prior to Fibery, Michael had worked on knowledge management for more than a decade. He also had built a successful project management software, Targetprocess.) You know that he’s an expert who can be trusted.

Interestingly, even though Michael writes differently from Sarah, they both leverage what they’re good at. Sarah does not try to produce treatises on software development philosophy, and Michael doesn’t gush out with his personal learnings from building a startup. That, I think, is the right way to do it.

How PostHog communicates who their founders are​

PostHog’s founders James and Tim don’t write 100 posts in 100 days or run a personal Instagram. But they’ve come up with something else to communicate what kind of people they are. And it’s something unique.

Well-written, concise bio​

First, both founders have decent profiles in the company handbook. These bios are short, clear, and humane. They’re also very specific. Where else have you seen the name of the CEO’s cat?

A screenshot of James Hawkins' bio in the PostHog Handbook

Personal README files​

Second, both James and Tim have an extensive README file (one, two) on how to work with them. These files give you an insight into their productivity habits, interests, and quirks. In fact, after reading them, you will likely have a better idea of the founders than you’d usually get from working at a company for a month!

For instance, James’s file has sections like:

  • Short bio. Includes very specific details like: “I tend to work 9am to 5pm with an hour for lunch, then I have a gap to have dinner with my family, then 9pm to around 11pm ish.”
  • Very clear areas of responsibility. No need to wonder what the hell the CEO is doing anymore!
  • Quirks. These are remarkably humble and open-minded, like:
    • “If I haven’t responded to something that you’ve sent me, that’s probably because I’ve read it and don’t feel particularly strongly - so just make a call on what to do if you don’t hear back in a reasonable time frame.”
    • “I’m a little disorganized. I compensate for this by making sure the teams I work on have this skill. Often I think this actually helps me prioritize the things that really matter.”
    • Explaining these quirks is an ingenious move. Besides explaining how to work with James, this section communicates that he’s profoundly self-aware and willing to accept and leverage his weaknesses. These qualities are very rare and incredibly valuable.
  • What I value. In stark contrast to most HR nonsense, these values are very clear, very specific, and written in English rather than HRese. (I just came up with this term: it means “legalese but for HR.”) Here are two examples:
    • “Proactivity. Do not ask me for permission to do things - I wouldn’t have hired you if I didn’t trust you. I’d rather 9 things get done well and 1 thing I disagree with than we don’t get anything done at all.”
    • “Directness impresses me. If you don’t like something please just say so. It makes for much healthier relationships.”

In addition to that, there’s also: How I can help you, How you can help me, My goals until end December 2022 (very specific!), Personal strategy, Execution todo (including “1 bike ride a week”!) and Archived todo.

In summary, this README page is a gem. I wish more founders had them.

A screenshot of James Hawkins' README in the PostHog Handbook

How we at Wasp communicate who our founders are​

“Who we are” section of every job description page​

Matija and Martin (the founders of Wasp) embedded a concise description of who they are right into each job description page in Notion. They knew that this is the first company artifact many candidates will see. So they saved candidates time and effort on digging up who the hell started Wasp.

Note the language and substance of this list. When you read it, you immediately get a sense of who Matija and Martin are as people — fun, easygoing, no-corporate-bullshit kinda guys. Now imagine it said something “more normal,” like: “The company was founded by seasoned entrepreneurs…” What impression would that make?

A screenshot of Wasp's job description page

2. TEAM — or, the team is great​

It is startling how little most startups tell you about their teams. Often all you get is a chessboard of faces and titles, which gives you no idea who these people are as people or how working with them will feel like. Given how crucial a reason “great team” is for most candidates, improving how you communicate it seems like a low-hanging fruit.

How Canny communicates who is on their team​

Decent team page​

The Canny’s difference starts with a team page. It has a dense summary of who each team member is as a person and includes high-quality, lively photos of everybody.

A screenshot of Canny's Team page

Look how specific those bios are. In most cases, all you get here is a generic “developer” or “marketer” without any personal details. Bios of robots, not people. No wonder nothing comes to mind, except perhaps for Agent Smith. But Canny’s bios are different. When you read them, you can actually imagine the person! They’re Neos in the world of Smiths.

Remarkable “Why work at Canny” blog post​

From there, it gets only better. Canny’s chief weapon for explaining their team is a blog post, the “Why work at Canny” blog post. Sarah wrote it back in the summer of 2021. It is full of quotes from team members and photos of their workdays and vacations. Real photos of real people. No wonder the comments section under the post abounds with raving fans willing to join the team straight away!

A screenshot of comments under the Canny's Why work at Canny blog post

Perhaps the best thing about this post is how little work it takes to create one. I imagine that collecting the data took some time, but the actual writing (it’s an 11-min read) took no more than a week. A week of work for a candidate magnet of such tremendous power? Sounds like a deal.

P.s. Sarah writes a lot more about their team in her yearly review posts, but I decided not to elaborate on those for the sake of clarity. You can check them out here: year 1, year 2, year 3, and year 4.

How Fibery communicates who is on their team​

Weird About Us page​

Unlike Canny and PostHog’s, Fibery’s About Us page doesn’t reveal much info about each team member. You will find no bios or README files there. But it clearly tells you one thing: the team is a bunch of weirdos. So, if weird is your thing, you’ll be attracted to Fibery like a moth to a flame. (Side note: Fibery managed to clearly explain their vision in one paragraph. This is rare.)

A screenshot of Fibery's About Us page

I’ve already mentioned Michael’s Startup Diary monthly blog series. What I didn’t say is that each post communicates something about the team: who did what that month, random Slack posts (links, quotes, tweets, and images), etc. If someone new joined that month, Michael writes a few paragraphs explaining who that person is, where they come from, what they’re going to do at Fibery, and even attaches a photo. Like Chris.

A screenshot of Fibery's Startup Diary blog post

How PostHog communicates who is on their team​

Team section in the company handbook​

At PostHog, every team member has a well-written, few-paragraphs-long bio and a stylish illustration on the Team section of the PostHog’s Handbook. (Which is a work of art worthy of its own blog post, by the way.) Many team members have their own README files, like the founders do. Check out Lottie Coxon’s, PostHog’s Graphic Designer’s README here, and some others here and here. Even a quick read through these bios and READMEs gives you a good idea of who PostHog has on board.

A screenshot of PostHog's team section in the handbook

Another screenshot of PostHog's team section in the handbook

Day-in-life videos from employees​

In addition to bios and READMEs, PostHog has a day-in-life video of Lottie, their graphic designer. It communicates a lot more information about what kind of person she is and how working at PostHog feels like than her bio. I wish they had more of those.

A screenshot from PostHog's graphic designer day-in-life video

Finally, PostHog’s handbook offers two more sections where candidates can learn even more about the team: Culture and Team structure. All are worth a read, and each tells you something new about the company and the team, nurturing your liking and respect for these people. Definitely worth stealing.

How we at Wasp communicate who is on our team​

“Meet the team” blog posts​

To help candidates understand who they will be working with, we at Wasp write a blog post about each new hire:

The posts are brief enough to be read in one sitting. Yet, they are very informative. Basically, each post is an interview, presented as an article. We hope they give candidates a good idea of who they'll be spending half of their waking time with.

A screenshot of Wasp's Meet the team blog post

3. CULTURE — or, the culture is amazing​

While researchers still argue about the ultimate definition, most of us understand culture as “what working here feels like” and/or “how we do things here.” We also understand how crucial it is for those looking for work. It seems glaringly obvious that startups should work hard on communicating their culture. Yet, most companies don’t. Or, even worse, they flood their websites with meaningless HR fluff, which only scares interesting people away. In short, communicating culture well is another low-hanging fruit waiting to be picked.

How Canny communicates their culture​

Canny does an outstanding job at communicating their culture. The primary tool they employ is, once again, their blog. (Note how multifunctional it is: founders, expertise, team, and now culture.) The posts in the Founder Stories category convey very well what working at Canny feels like. Here are a few examples.

“Why work at Canny” blog post​

I’ll risk repeating myself, but this post so beautifully explains Canny’s culture that I couldn’t resist. It mentions why and how they work remotely, how they do team retreats (with photos and a video from Lisbon!), and how they had fun together playing weird Zoom games when travel was not an option due to Covid.

Pay attention to the imagery. It communicates a lot more information than any lengthy, elaborate description would. Indeed, a picture is often worth a thousand words.

A photo of Canny's two team members hacking in Denver

“Lessons from a year of team retreats” blog post​

Instead of saying that “team is our priority” or “we invest in our people,” Sarah shows what they’ve done to support their team.

Again, note how specific the imagery is.

A photo from Canny's Lessons from a year of team retreats blog post

Interestingly, Sarah’s post isn’t framed as “hey we do many team retreats, we’re awesome, come work for us.” If they wrote that, the reader would feel uneasy. They would sense bragging. That’s why the explicit message in the post is what Canny learned doing team retreats, not that they’ve done many. This explicit message, however, implies that they indeed have done many retreats! It sends a message that Canny cares for their employees without explicitly saying so. This is what true mastery looks like.

“The end of our digital nomad journey” blog post​

Although this post describes Sarah and Andrew’s personal nomad experience, Sarah managed to reveal Canny’s culture through it. To do that, she described how the team worked on Canny during those nomad years. She also wrote about their communication struggles, routines, and a lot more. And, again, look at how effectively her seemingly imperfect screenshots and photos transmit the vibe!

A photo from Canny's The end of our digital nomad journey blog post

Another photo from Canny's The end of our digital nomad journey blog post

How Fibery communicates their culture​

While Fibery’s culture is different from Canny’s, they also communicate it well. Their primary tool is a weird, quirky website full of special projects that give you a sense of how they do things at Fibery and what working there feels like.

Anxiety page​

The first project is Fibery’s /anxiety page. Launched in 2019, it mocks every serious enterprise software out there with puns like “Yet another collaboration tool” as the page title, “Mistake” as a sign-up button text, and, my favorite, “Try—Suffer—Quit” page structure.

A screenshot of Fibery's /anxiety page

One day three years ago, someone submitted this page to Hacker News. The post surged to the top of the frontpage, stayed there for many hours, and got 705 upvotes and 145 comments from people all over the world relating to Fibery’s culture. Why? Because it felt real.

Here’s a glimpse of what people wrote in the comments:

A screenshot of Hacker News comments on Fibery's /anxiety page

Another screenshot of Hacker News comments on Fibery's /anxiety page

Remote page​

The second special project Fibery did to communicate their culture is the /remote page. It shows what working from home is really like. It’s the funniest thing I’ve ever seen done by a software startup. (Have you ever seen a CEO being licked by a dog?) It also shows how the Fibery team works and even how they use Fibery to build Fibery. Like Canny’s “Lessons from a year of team retreats” blog post, it does so implicitly. A true masterpiece.

Weird, humorous site​

Broadly, the whole site screams that Fibery is a place for misfits, rebels, and trouble makers; the place where such people will be valued and will feel like home; the place built around brutal honesty and spicy humor.

The “What (non-)customers say” section is worth a mention. Over my nine years in startups, I haven’t seen a site that a) lists bad customer reviews; and b) uses 💩 emoji as a filter. Again, this is telling. It says a lot about who they are as people: humble, real, and fond of humor.

A screenshot of Fibery's About Us page, What non-customers say section

How PostHog communicates their culture​

Comprehensive company handbook covering all-things culture​

PostHog’s way of communicating their culture is the most explicit of all four examples, yet very effective. Their primary tool is the PostHog Handbook, which covers virtually every aspect of what working at PostHog feels like: interviews, onboarding, training, management, communication, and even firing. (They call it offboarding.)

The handbook goes all the way up to the high-level strategy, which is very clear. Notably, PostHog’s strategy section not only puts forth ambitious goals but actually explains how exactly the company will get there.

The values section is very specific; perhaps the most specific I’ve ever seen. PostHog does not merely list their values as meaningless abstractions but supports them with evidence. Some values have many paragraphs of examples demonstrating how the team follows them.

A screenshot of the Values section in the PostHog's handbook

They also have a specific Culture page with a 5-minute video from the CEO explaining how they designed PostHog for remote work from day one, which nicely complements the text.

A screenshot from James Hawkins's video

In summary, if Canny’s weapon of choice is the blog and Fibery’s is the website, then PostHog’s is definitely the handbook. It’s a work of art.

How we at Wasp communicate our culture​

Easygoing vibe from memes, copy, and imagery​

Unlike Posthog, we at Wasp don’t (yet) have a dedicated Culture page. We are too small for that. But that doesn’t stop us from showing what working at Wasp feels like. We just use different tools.

Our Twitter, blog, and monthly updates abound with memes, GIFs, and hilarious imagery. Plus, we write them in a humorous, lighthearted, easygoing style. By just scrolling through these things for a few minutes, candidates can understand that we aren’t some corporate bros. And if they like working on interesting things while having fun, they won’t help but feel an inkling to reach out.

A funny image from Wasp's blog post about GitHub Copilot

A photo of Wasp's team packing t-shirts for users

4. PROGRESS — or, the business is doing well​

When you just closed an $80 million Series B or signed Facebook as a customer, communicating progress is easy. You just state these facts. However, most companies need to attract great people way before Series B. In fact, it is these very people who’re going to get you there. As most startups are secretive about how things are going, communicating that things are going somehow — no matter how negligible your progress in contrast to the big guys — becomes quite an advantage. It immediately de-risks the opportunity in the candidate’s eyes. So, if EXPERTISE is about convincing candidates that you know how to build the wings, PROGRESS is about showing them the half-built carcass on your way down. Both are important if you want great people to jump off the cliff with you.

How Canny communicates their progress​

To give candidates a sense that things are moving, that this company is not some long slog but a place where progress is made every day, that they can become a part of something that’s growing and, therefore, can grow themselves, to do all that, Canny does two things.

“Year in review” blog posts​

The first one is their “Year in review” blog post series. Such comprehensive, thoughtful reviews are rare in the startup world. What is even rarer is when these posts span over four consecutive years. It sends a message that the founders are persistent and devoted to making this company successful.

Below are all Canny’s year-in-review posts in a sequential order:

A screenshot of Canny's Year in review blog post

Important revenue milestones blog posts​

In addition to year-in-review posts, Sarah writes about hitting notable revenue milestones. Like with yearly reviews, such transparency is rare. It attracts attention, causes liking, and builds trust.

For example:

A screenshot of Canny's How we built a $1m ARR SaaS startup blog post

Short tweets with progress summary​

Finally, Sarah occasionally tweets short summaries of their progress, like this one. These tweets work like ads. Over time, a candidate’s brain fuses them into a broader idea like “Canny is growing” or “Canny is doing well.” Then, once a candidate decides to change jobs, it nudges the candidate to consider Canny.

A screenshot of Sarah’s tweet with progress update

How Fibery communicates their progress​

Startup Diary blog posts​

The most notable thing Fibery does to communicate their progress is the Startup Diary blog posts series written by the founder, Michael, every month, for the past 45 months. It’s the longest series of monthly updates I know. In these posts, Michael honestly shares everything that’s going on with the company: the good, the bad, and the ugly.

Below are just a few examples, selected by me. You can study all Fibery’s monthly updates here.

  • #2 Slow September 2018 — Fibery startup progress in September 2018. Slow month with not so many news. First positive feedback. Company name selection.
  • #6 Planning Private Beta in January 2019 — Fibery startup progress in January 2019: Private beta goals, selecting a market positioning (hard), apps re-design.
  • #10 Burn in May 2019 — Several people burned out, new features are delivered, public release will be sooner (we hope) (despite ill fortune).
  • #16 Crazy November 2019 — Fibery 1.0 is silently launched. Silence is hard to keep. HackerNews front page. Twitter madness. 3000 registered accounts.
  • #17 Fragmented December 2019 — Public announcements moved to January. +Lena. Tons of feedback. First money! Hype is over. We consider rising a ~$4M round.
  • #35 Raised $3.1M in July 2021 — TLDR: We closed $3.1M seed round. Building a second brain for teams. Fibery mission. Building in Public. Automation rules. Documents and Rich Text history.
  • #36 20k MRR in August 2021 — Special Startup Diary edition. 20k MRR & 15 new customers! +Chris. +Sales agency. 4 case studies. Airtable integration & notify people action.
  • ($30K MRR) #42 Connecting the dots in April 2022 — TLDR: 🇺🇦 Ukrainian war affected our performance. $30K MRR 🐌. 69 reviews in G2 ❤️. Marketing for customer-built products is hard 🥉. 12 customer stories 👻. 2 hours downtime 🥲. New navigation ⛵️. My Space 🔒.

Imagine a candidate who is considering two or more similar startups. Guess what might convince them to go with Fibery? Progress. Or, more exactly, an understanding that Fibery is persistently making progress and, therefore, has a decent chance to become successful. Delivered through these very updates.

Last year, Michael (Fibery’s CEO) started writing year-in-review posts too. I didn’t mention them because there’s just one post for now. You can read his 2021 review here.

Open Startup page with metrics​

The second tool that Fibery employs to share their progress is the /open-startup page. Like monthly updates, it gives candidates a good idea of how the business is doing. This understanding, however, comes from a different source: pure numbers. And numbers often speak louder than words.

A screenshot of Fibery's Open startup page

How PostHog communicates their progress​

Story page in the handbook​

In the PostHog’s handbook, they have a page called Story. It succinctly shows the milestones the company has hit so far. For each milestone, they offer a clear and concise explanation of what happened, sometimes no longer than a sentence. As a result, candidates can get a good idea of how things are going in less than a minute. That’s something to aspire to.

Here’s the section titles:

  • Jan 2020: The start
  • Feb 2020: Launch
  • Apr 2020: $3M Seed round
  • May 2020: First 1,000 users
  • Oct 2020: Billions of events supported
  • Nov 2020: Building a platform
  • Dec 2020: $9M Series A
  • Jun 2021: $15M Series B
  • Sep 2021: Product Market fit achieved for PostHog Scale

A screenshot of PostHog's Story page

How we at Wasp communicate our progress​

Blog posts covering big milestones (YC, $1.5m seed)​

For each milestone, Matija and Martin (Wasp founders) write a blog post describing not only what they accomplished but also how they did it.

For example, when Wasp got into YC, they didn’t just post the news on Twitter. They wrote a blog about their journey to Y Combinator. It got thousands of views.

Same with fundraising. When Wasp closed a $1.5m seed, Matija documented and shared their fundraising learnings in a blog post. It ended up on the HN frontpage. (Incidentally, this post communicates something important about the founders. It takes persistence to run 250+ meetings in 98 days.)

A screenshot of Wasp's fundraising learnings blog post

Monthly newsletter with updates​

To keep the momentum, Matija also writes a monthly newsletter. It’s similar to Michael’s Startup Diary in substance, but has a different style. Wasp style. (Which, again, communicates our culture.)

Like PostHog’s Story page, Wasp’s monthly updates give candidates a bird’s eye view over everything that’s happened in the past two years. To anyone interested in connecting the dots, this page is a gem.

A screenshot of Wasp's monthly newsletter archives

So, why should people join your startup?​

The founders are interesting / fun / smart / human / you name it

The team is great

The culture is amazing

The business is doing well

By communicating all these reasons well, what Canny, Fibery, PostHog, and (we hope!) Wasp really end up transmitting is two powerful messages:

  • The company is likely to succeed
  • Working there will be awesome

These two messages are the real answer to “why people should join your company.” The trick, however, and the reason why I wrote this post, is that you can only transmit them indirectly. You can’t say “our founders are great.” You need to provide candidates with many-many facts about the founders, which their minds will then fuse into this abstract conclusion. Ditto for expertise, team, culture, and progress. Eventually, these first-level abstractions will blend into still broader ones: “the company is likely to succeed” and “working there will be awesome.”

Thus, there’s no single, ultimate answer to “why people should join your company.” There’s only a complex system of concrete, specific units of information from which candidates make the answer themselves. In other words, you can’t teach them why your company is likely to succeed and why working here will be awesome. But you can outline the facts and let them learn for themselves. I hope this post shows how to do that outlining well, and I hope you will apply this knowledge to bring talented people onboard and build great things.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/08/26/how-and-why-i-got-started-with-haskell.html b/blog/2022/08/26/how-and-why-i-got-started-with-haskell.html index 2ee304c732..ee40673af0 100644 --- a/blog/2022/08/26/how-and-why-i-got-started-with-haskell.html +++ b/blog/2022/08/26/how-and-why-i-got-started-with-haskell.html @@ -19,13 +19,13 @@ - - + + -
-

How and why I got started with Haskell

· 8 min read
Shayne Czyzewski

I have been programming professionally for over a decade, using a variety of languages day-to-day including Ada, C, Java, Ruby, Elixir, and JavaScript. I’ve also tried some obscure ones, albeit less frequently and for different purposes: MIPS assembly language and OCaml for academic work (I’m a BS, MS, and PhD dropout in CS), and Zig for some side projects. In short, I like learning new languages (at least at a surface level) and have been exposed to different programming paradigms, including functional.

Yet, I have never done Haskell. I’ve wanted to learn it since my college days, but never got the time. In late 2021, though, my curiosity took over. I wanted to see for myself if the mystique and the Kool-Aid hype (or hate) around it are justified. :P So, I decided I’d start learning it on the side and also look for a company that uses it as my next gig. That’s how my Haskell journey started, and how I got into Wasp a few months later.

Why learn Haskell?​

Haskell seems to have an aura of superiority around it. Many niche and heavily academically-inspired languages do. These languages seem to be used by the enlightened minds and allow you to quickly write complex programs in a fraction of the time with significantly less code. Lisp is amongst these languages, too. Yet, nobody uses them for anything real — only toy projects. (While stroking their long, grey beards under a tree, ruminating on the philosophy of computer science.) At least, that’s the impression I got in college and at work. So, what makes Haskell interesting to learn, let alone want to use professionally?

First, it is functional as it gets. While I have used lambdas and functional concepts like map in non-functional languages, the fact that these were my only choice was really interesting to me. After years of extensive OO usage, I’ve come to appreciate this epigram by Alan Perlis. I think it captures a mindset shift between the two paradigms:

“It is better to have 100 functions operate on one data structure than 10 functions on 10 data structures.” — Alan Perlis

In OO, you create lots of classes with lots of methods. In functional, you have far fewer data structures (mostly list) with a lot more functions. So basically more functions to operate on fewer nouns, whereas OO is lots of nouns, each with many bespoke methods. (The first comment on this Stack Overflow thread explains it really well.)

Besides, I liked the idea of referential transparency when writing pure functions. It means that you get the same result back every time you invoke a function, without fear of unknown side effects. (But the language does offer the flexibility to have side effects like IO, via Monads.) I also liked having only immutable data structures — they make reasoning about the system and data flow easier. There were many things like these two that I liked. The point is that thinking functionally really changes the way you structure and solve problems, so I was curious to give it a go.

Second, Haskell is lazy. While there are pros and cons to this, it feels undeniably different. Most languages are strict, in that all function arguments are evaluated before invoking a function. This is required because of side effects; to have some expectations regarding the order in which things will run. Haskell does the opposite: it delays evaluation until it’s actually needed.

One contrived yet helpful example of laziness is infinite data structures. Below, we define fibs as an infinite List of Integer values, by using references to itself! (You can find a runnable example here.) 

fibs :: [Integer]
fibs = 0 : 1 : zipWith (+) fibs (tail fibs)

take 10 fibs -- [0,1,1,2,3,5,8,13,21,34]

There’s a downside to laziness, too. It makes it harder to reason about performance and resource utilization. But the idea that you can define things in a declarative way but know that they are evaluated only when needed is a pretty eye-opening way to program.

To sum up: Haskell is functional, lazy, and strongly statically typed. Just the trifecta that gets me out of bed in the morning! :D So, how did I go about learning it?

Hello Haskell!​

I started by reading the canonical Haskell newbie resource, “Learn You a Haskell for Great Good!,” often abbreviated LYAH. It was very entertaining, and I learned a lot from it. At times, I wanted it to get to the point more quickly. Still, despite the amusing images and often lengthy examples, it provided me with a great conceptual foundation. I highly recommend it as your first read — it is a really well-written resource for beginners.

After I was about 80% done with LYAH, I switched to a more recent but still popular book: “Haskell Programming from First Principles.” I liked that it started with fundamentals and then moved to more complex topics, slowly but steadily developing my understanding. It was pretty long, though, and sometimes went too far into the weeds. It also had a tinge of intellectual flexing at certain points. Still, it was a good read. I’d read it again if I were starting over.

I also tried a Haskell course from Google. Despite being brief, it explains the key concepts in a relatively complete way. If videos are your thing, it might be a solid way to get up to speed.

In short, skimming an intro book to get your foundation solid would be the best bet. I’d also recommend trying out many different online resources when covering more intermediate topics, like Monad Transformers, for example. And don’t worry if it takes a while to start feeling comfortable with things that are pretty specific to Haskell! It just takes some time, and often it is more confusing to derive/deeply understand than to just start using them at first. The understanding will come over time. (Of course, sometimes pictures help!)

Setup and IDE support​

Getting Haskell up and running was surprisingly straightforward, even though I ran it on an M1 MacBook Air, which was considered a pretty new architecture in 2021. Since the entire toolchain was not fully ARM-compatible back then, some of the setup advice required a bit of modification. But that was no big deal: I used ghcup, installed HLS in VS Code, and bam! — I had Haskell up and running. It was a pretty nice experience.

Some minor downsides I recall:

  • There doesn’t seem to be a consensus on which build and package management tool to use, Cabal or Stack. However, unless you’re doing something super specific, it’s not an irreversible decision. At Wasp, we started with Stack but then migrated to Cabal since it better fit our setup and workflows. It was pretty seamless.
  • One thing I do miss from other IDEs is breakpoint debugging. Technically, there’s some support for it in Haskell, but I don’t think many use it. Breakpoints and lazy evaluation don’t seem to be BFFs.

0-60 at work​

For someone with experience in several different languages, it is pretty achievable to be able to solve minor bugs/features in Haskell after a few weeks of learning. At least, it was for me. I certainly struggled on best practices and such, and my code reviews involved some Haskell golfing comments for sure :) But I could make it do what I wanted it to do from the functionality perspective. Kudos to the mostly helpful compiler errors (with a bit of practice reading) and the Internet!

Hopefully, your code base demonstrates established project and Haskell patterns, so you can learn as you poke around, and your early code reviewers are supportive coworkers who can explain things as part of their suggestions. I was quite fortunate in that regard: the Wasp team values teaching and learning, and the codebase uses what is called “Simple Haskell”, which limits the use of excessive language extensions in the hopes to keep the core language and concepts as tight as possible. (Note: there are Haskell experts who view this as a severe limitation of the capabilities of the language, but as a newbie, I was happy they did it.)

So, was the juice worth the squeeze?​

Learning Haskell took considerable time and effort. It was completely different from any language I had used before. Yet, I am very happy I embarked on this journey. Even if you do not intend to get a job using Haskell, I still think learning it is worthwhile just to expand your programming point of view and master functional concepts. And for a select set of project types (like writing a compiler for a full-stack web DSL), I feel it really will make you more productive over time. Give an intro to Haskell tutorial or video a try some weekend and let me know what you think! I’m at shayne at wasp-lang dot dev dot com.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

How and why I got started with Haskell

· 8 min read
Shayne Czyzewski

I have been programming professionally for over a decade, using a variety of languages day-to-day including Ada, C, Java, Ruby, Elixir, and JavaScript. I’ve also tried some obscure ones, albeit less frequently and for different purposes: MIPS assembly language and OCaml for academic work (I’m a BS, MS, and PhD dropout in CS), and Zig for some side projects. In short, I like learning new languages (at least at a surface level) and have been exposed to different programming paradigms, including functional.

Yet, I have never done Haskell. I’ve wanted to learn it since my college days, but never got the time. In late 2021, though, my curiosity took over. I wanted to see for myself if the mystique and the Kool-Aid hype (or hate) around it are justified. :P So, I decided I’d start learning it on the side and also look for a company that uses it as my next gig. That’s how my Haskell journey started, and how I got into Wasp a few months later.

Why learn Haskell?​

Haskell seems to have an aura of superiority around it. Many niche and heavily academically-inspired languages do. These languages seem to be used by the enlightened minds and allow you to quickly write complex programs in a fraction of the time with significantly less code. Lisp is amongst these languages, too. Yet, nobody uses them for anything real — only toy projects. (While stroking their long, grey beards under a tree, ruminating on the philosophy of computer science.) At least, that’s the impression I got in college and at work. So, what makes Haskell interesting to learn, let alone want to use professionally?

First, it is functional as it gets. While I have used lambdas and functional concepts like map in non-functional languages, the fact that these were my only choice was really interesting to me. After years of extensive OO usage, I’ve come to appreciate this epigram by Alan Perlis. I think it captures a mindset shift between the two paradigms:

“It is better to have 100 functions operate on one data structure than 10 functions on 10 data structures.” — Alan Perlis

In OO, you create lots of classes with lots of methods. In functional, you have far fewer data structures (mostly list) with a lot more functions. So basically more functions to operate on fewer nouns, whereas OO is lots of nouns, each with many bespoke methods. (The first comment on this Stack Overflow thread explains it really well.)

Besides, I liked the idea of referential transparency when writing pure functions. It means that you get the same result back every time you invoke a function, without fear of unknown side effects. (But the language does offer the flexibility to have side effects like IO, via Monads.) I also liked having only immutable data structures — they make reasoning about the system and data flow easier. There were many things like these two that I liked. The point is that thinking functionally really changes the way you structure and solve problems, so I was curious to give it a go.

Second, Haskell is lazy. While there are pros and cons to this, it feels undeniably different. Most languages are strict, in that all function arguments are evaluated before invoking a function. This is required because of side effects; to have some expectations regarding the order in which things will run. Haskell does the opposite: it delays evaluation until it’s actually needed.

One contrived yet helpful example of laziness is infinite data structures. Below, we define fibs as an infinite List of Integer values, by using references to itself! (You can find a runnable example here.) 

fibs :: [Integer]
fibs = 0 : 1 : zipWith (+) fibs (tail fibs)

take 10 fibs -- [0,1,1,2,3,5,8,13,21,34]

There’s a downside to laziness, too. It makes it harder to reason about performance and resource utilization. But the idea that you can define things in a declarative way but know that they are evaluated only when needed is a pretty eye-opening way to program.

To sum up: Haskell is functional, lazy, and strongly statically typed. Just the trifecta that gets me out of bed in the morning! :D So, how did I go about learning it?

Hello Haskell!​

I started by reading the canonical Haskell newbie resource, “Learn You a Haskell for Great Good!,” often abbreviated LYAH. It was very entertaining, and I learned a lot from it. At times, I wanted it to get to the point more quickly. Still, despite the amusing images and often lengthy examples, it provided me with a great conceptual foundation. I highly recommend it as your first read — it is a really well-written resource for beginners.

After I was about 80% done with LYAH, I switched to a more recent but still popular book: “Haskell Programming from First Principles.” I liked that it started with fundamentals and then moved to more complex topics, slowly but steadily developing my understanding. It was pretty long, though, and sometimes went too far into the weeds. It also had a tinge of intellectual flexing at certain points. Still, it was a good read. I’d read it again if I were starting over.

I also tried a Haskell course from Google. Despite being brief, it explains the key concepts in a relatively complete way. If videos are your thing, it might be a solid way to get up to speed.

In short, skimming an intro book to get your foundation solid would be the best bet. I’d also recommend trying out many different online resources when covering more intermediate topics, like Monad Transformers, for example. And don’t worry if it takes a while to start feeling comfortable with things that are pretty specific to Haskell! It just takes some time, and often it is more confusing to derive/deeply understand than to just start using them at first. The understanding will come over time. (Of course, sometimes pictures help!)

Setup and IDE support​

Getting Haskell up and running was surprisingly straightforward, even though I ran it on an M1 MacBook Air, which was considered a pretty new architecture in 2021. Since the entire toolchain was not fully ARM-compatible back then, some of the setup advice required a bit of modification. But that was no big deal: I used ghcup, installed HLS in VS Code, and bam! — I had Haskell up and running. It was a pretty nice experience.

Some minor downsides I recall:

  • There doesn’t seem to be a consensus on which build and package management tool to use, Cabal or Stack. However, unless you’re doing something super specific, it’s not an irreversible decision. At Wasp, we started with Stack but then migrated to Cabal since it better fit our setup and workflows. It was pretty seamless.
  • One thing I do miss from other IDEs is breakpoint debugging. Technically, there’s some support for it in Haskell, but I don’t think many use it. Breakpoints and lazy evaluation don’t seem to be BFFs.

0-60 at work​

For someone with experience in several different languages, it is pretty achievable to be able to solve minor bugs/features in Haskell after a few weeks of learning. At least, it was for me. I certainly struggled on best practices and such, and my code reviews involved some Haskell golfing comments for sure :) But I could make it do what I wanted it to do from the functionality perspective. Kudos to the mostly helpful compiler errors (with a bit of practice reading) and the Internet!

Hopefully, your code base demonstrates established project and Haskell patterns, so you can learn as you poke around, and your early code reviewers are supportive coworkers who can explain things as part of their suggestions. I was quite fortunate in that regard: the Wasp team values teaching and learning, and the codebase uses what is called “Simple Haskell”, which limits the use of excessive language extensions in the hopes to keep the core language and concepts as tight as possible. (Note: there are Haskell experts who view this as a severe limitation of the capabilities of the language, but as a newbie, I was happy they did it.)

So, was the juice worth the squeeze?​

Learning Haskell took considerable time and effort. It was completely different from any language I had used before. Yet, I am very happy I embarked on this journey. Even if you do not intend to get a job using Haskell, I still think learning it is worthwhile just to expand your programming point of view and master functional concepts. And for a select set of project types (like writing a compiler for a full-stack web DSL), I feel it really will make you more productive over time. Give an intro to Haskell tutorial or video a try some weekend and let me know what you think! I’m at shayne at wasp-lang dot dev dot com.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/09/02/how-to-get-started-with-haskell-in-2022.html b/blog/2022/09/02/how-to-get-started-with-haskell-in-2022.html index 4405c2e8fc..4805620eba 100644 --- a/blog/2022/09/02/how-to-get-started-with-haskell-in-2022.html +++ b/blog/2022/09/02/how-to-get-started-with-haskell-in-2022.html @@ -19,13 +19,13 @@ - - + + -
-

How to get started with Haskell in 2022 (the straightforward way)

· 7 min read
Martin Sosic

Haskell is a unique and beautiful language that is worth learning, if for nothing else, then just for the concepts it introduces and their potential to expand your view on programming.

I have been programming in Haskell on and off since 2011 and professionally for the past 2 years, building a compiler. While in that time Haskell has become much more beginner-friendly, I keep seeing beginners who are overwhelmed by numerous popular options for build tools, installers, introductory educational resources, and similar. Haskell’s homepage getting a call from the previous decade to give them their UX back :D also doesn’t help!

That is why I decided to write this opinionated and practical post that will tell you exactly how to get started with Haskell in 2022 in the most standard / common way. Instead of worrying about decisions that you are not equipped to make at the moment (e.g. “what is the best build tool?”), you can focus on enjoying learning Haskell :)!

TLDR / Super opinionated summary​

  1. For setup, use GHCup. Install GHC, HLS, and cabal.
  2. As a build tool, use cabal.
  3. For editor, use VS Code with Haskell extension. Or, use emacs/vim/....
  4. Join r/haskell. Feel free to ask for help!
  5. To learn the basics of Haskell, read the LYAH book and build a blog generator in Haskell. Focus on getting through stuff instead of understanding everything fully; you will come back to it later again.

1. Setup: Use GHCup for seamless installation​

GHCup is a universal installer for Haskell. It will install everything you need to program in Haskell and will help you manage those installations in the future (update, switch versions, and similar). It is simple to use and works the same way on Linux, macOS, and Windows. It gives you a single central place/method to take care of your Haskell installation so that you don’t have to deal with OS-specific issues.

To install it, follow instructions at GHCup. Then, use it to install the Haskell Toolchain (aka stuff that you need to program in Haskell).

Haskell Toolchain consists of:

  1. GHC -> Haskell compiler
  2. HLS -> Haskell Language Server -> your code editor will use this to provide you with a great experience while editing Haskell code
  3. cabal -> Haskell build tool -> you will use this to organize your Haskell projects, build them, run them, define dependencies, etc.
  4. Stack -> cabal alternative, which you won’t need for now since we’ll go with cabal as our build tool of choice

2. Build tool: Use cabal​

There are two popular build tools for Haskell: cabal and Stack. Both are widely used and have their pros and cons. So, one of the hard choices beginners often face is which one to use.

Some time ago, cabal was somewhat hard to use (complex, “dependency hell”). That’s why Stack was created: a user-friendly build tool that solves some of the common issues of cabal. (Interestingly, Stack uses cabal’s core library as its backend!) However, as Stack was being developed, cabal advanced, too. Many of its issues have been solved, making it a viable choice for beginners.

In 2022, I recommend cabal to beginners. I find it a bit easier to understand when starting out (no resolvers), it works well out of the box with GHCup and the rest of the ecosystem, and it seems to be better maintained lately.

3. Editor: VS Code is a safe bet​

HLS (Haskell Language Server) brings all the cool IDE features to your editor. So, as long as your editor has a decent Haskell language extension that utilizes HLS, you are good.

The safest bet is to go with Visual Studio Code — it has a great Haskell extension that usually works out of the box. A lot of Haskell programmers also use Emacs and Vim. I can confirm they also have good support for Haskell.

4. Community: r/haskell and more​

Haskell community is a great place to ask for help and learn about new developments in the ecosystem. I prefer r/haskell -> it tracks all the newest events and no question goes unanswered. There is also Haskell Discourse, where a lot of discussions happen, including the more official ones. A lot of Haskellers are still active on IRC, but I find it too complex and outdated to use.

Check https://www.haskell.org/community for a full list of Haskell communities.

5. Learning: You don’t need a math degree, just grab a book​

There is a common myth going around that you need a special knowledge of math (PhD in category theory!) to be able to program in Haskell properly. From my experience, this is as far from the truth as it can be. It is certainly not needed, and I seriously doubt it helps even if you have it. Maybe for some very advanced Haskell stuff, but certainly not for junior/intermediate level.

Instead, learning Haskell is the same as learning other languages -> you need a healthy mix of theory and practice. The main difference is that there will be more unusual/new concepts than you are used to, which will require some additional effort. But these new concepts are also what makes learning Haskell so fun!

I recommend starting with a book for beginners, LYAH. It has an online version that you can read for free, or you can buy a printed version if you like physical books.

If you don't like LYAH, consider other popular books for beginners (none of them are free though):

  1. Haskell Programming from first principles
  2. Get Programming with Haskell
  3. Programming in Haskell

Whatever book you go with, don’t get stuck for too long on concepts that are confusing to you, especially towards the end of the book. Some concepts will just need time to click; don’t expect to grasp it all on the first try. Whatever you do grasp from the first read will likely be more than enough to get going with your first projects in Haskell. You can always come back to those complex concepts later and understand them better. Also, don’t be shy to ask the community -> there are many Haskellers out there happy to support you in your learning!

note

When I say "don't get stuck", I don't mean you should skip the difficult concept after the first hurdle. No, you should spend some hours experimenting, looking at it from different angles, playing with it, trying to crack it. But you shouldn't spend days trying to understand the same concept (e.g. function as a monad) and then feel defeated due to not grasping it 100%. Instead, if you put proper effort but stuff is not completely clicking, tap yourself on the back and move on for now.

Once you take the first pass through the book, I recommend doing a project or two. You can come up with an idea yourself, or you can follow one of the books that guide you through it.

For example:

  1. Learn Haskell by building a blog generator -> free, starts from 0 knowledge, and could even be used as the very first resource, instead of e.g. LYAH.
  2. The Simple Haskell Handbook -> not free, expects you to know the basics of Haskell already

Once you have more experience with projects, I would recommend re-reading your beginner book of choice. This time, you can skip the parts you already know and focus on what was confusing before. You will likely have a much easier time grasping those harder concepts.

p.s. If you are looking for a bit of extra motivation, check the blog post my teammate Shayne recently wrote about his journey with Haskell. He started in late 2021 and has already made huge progress!

Good luck with Haskell! If you have Haskell questions for me or the rest of the Wasp team, drop me a line at “martin” ++ “@” ++ concat [”wasp”, “-”, “lang”] <> “.dev” , or write to #haskell channel in Wasp-lang Discord server.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

How to get started with Haskell in 2022 (the straightforward way)

· 7 min read
Martin Sosic

Haskell is a unique and beautiful language that is worth learning, if for nothing else, then just for the concepts it introduces and their potential to expand your view on programming.

I have been programming in Haskell on and off since 2011 and professionally for the past 2 years, building a compiler. While in that time Haskell has become much more beginner-friendly, I keep seeing beginners who are overwhelmed by numerous popular options for build tools, installers, introductory educational resources, and similar. Haskell’s homepage getting a call from the previous decade to give them their UX back :D also doesn’t help!

That is why I decided to write this opinionated and practical post that will tell you exactly how to get started with Haskell in 2022 in the most standard / common way. Instead of worrying about decisions that you are not equipped to make at the moment (e.g. “what is the best build tool?”), you can focus on enjoying learning Haskell :)!

TLDR / Super opinionated summary​

  1. For setup, use GHCup. Install GHC, HLS, and cabal.
  2. As a build tool, use cabal.
  3. For editor, use VS Code with Haskell extension. Or, use emacs/vim/....
  4. Join r/haskell. Feel free to ask for help!
  5. To learn the basics of Haskell, read the LYAH book and build a blog generator in Haskell. Focus on getting through stuff instead of understanding everything fully; you will come back to it later again.

1. Setup: Use GHCup for seamless installation​

GHCup is a universal installer for Haskell. It will install everything you need to program in Haskell and will help you manage those installations in the future (update, switch versions, and similar). It is simple to use and works the same way on Linux, macOS, and Windows. It gives you a single central place/method to take care of your Haskell installation so that you don’t have to deal with OS-specific issues.

To install it, follow instructions at GHCup. Then, use it to install the Haskell Toolchain (aka stuff that you need to program in Haskell).

Haskell Toolchain consists of:

  1. GHC -> Haskell compiler
  2. HLS -> Haskell Language Server -> your code editor will use this to provide you with a great experience while editing Haskell code
  3. cabal -> Haskell build tool -> you will use this to organize your Haskell projects, build them, run them, define dependencies, etc.
  4. Stack -> cabal alternative, which you won’t need for now since we’ll go with cabal as our build tool of choice

2. Build tool: Use cabal​

There are two popular build tools for Haskell: cabal and Stack. Both are widely used and have their pros and cons. So, one of the hard choices beginners often face is which one to use.

Some time ago, cabal was somewhat hard to use (complex, “dependency hell”). That’s why Stack was created: a user-friendly build tool that solves some of the common issues of cabal. (Interestingly, Stack uses cabal’s core library as its backend!) However, as Stack was being developed, cabal advanced, too. Many of its issues have been solved, making it a viable choice for beginners.

In 2022, I recommend cabal to beginners. I find it a bit easier to understand when starting out (no resolvers), it works well out of the box with GHCup and the rest of the ecosystem, and it seems to be better maintained lately.

3. Editor: VS Code is a safe bet​

HLS (Haskell Language Server) brings all the cool IDE features to your editor. So, as long as your editor has a decent Haskell language extension that utilizes HLS, you are good.

The safest bet is to go with Visual Studio Code — it has a great Haskell extension that usually works out of the box. A lot of Haskell programmers also use Emacs and Vim. I can confirm they also have good support for Haskell.

4. Community: r/haskell and more​

Haskell community is a great place to ask for help and learn about new developments in the ecosystem. I prefer r/haskell -> it tracks all the newest events and no question goes unanswered. There is also Haskell Discourse, where a lot of discussions happen, including the more official ones. A lot of Haskellers are still active on IRC, but I find it too complex and outdated to use.

Check https://www.haskell.org/community for a full list of Haskell communities.

5. Learning: You don’t need a math degree, just grab a book​

There is a common myth going around that you need a special knowledge of math (PhD in category theory!) to be able to program in Haskell properly. From my experience, this is as far from the truth as it can be. It is certainly not needed, and I seriously doubt it helps even if you have it. Maybe for some very advanced Haskell stuff, but certainly not for junior/intermediate level.

Instead, learning Haskell is the same as learning other languages -> you need a healthy mix of theory and practice. The main difference is that there will be more unusual/new concepts than you are used to, which will require some additional effort. But these new concepts are also what makes learning Haskell so fun!

I recommend starting with a book for beginners, LYAH. It has an online version that you can read for free, or you can buy a printed version if you like physical books.

If you don't like LYAH, consider other popular books for beginners (none of them are free though):

  1. Haskell Programming from first principles
  2. Get Programming with Haskell
  3. Programming in Haskell

Whatever book you go with, don’t get stuck for too long on concepts that are confusing to you, especially towards the end of the book. Some concepts will just need time to click; don’t expect to grasp it all on the first try. Whatever you do grasp from the first read will likely be more than enough to get going with your first projects in Haskell. You can always come back to those complex concepts later and understand them better. Also, don’t be shy to ask the community -> there are many Haskellers out there happy to support you in your learning!

note

When I say "don't get stuck", I don't mean you should skip the difficult concept after the first hurdle. No, you should spend some hours experimenting, looking at it from different angles, playing with it, trying to crack it. But you shouldn't spend days trying to understand the same concept (e.g. function as a monad) and then feel defeated due to not grasping it 100%. Instead, if you put proper effort but stuff is not completely clicking, tap yourself on the back and move on for now.

Once you take the first pass through the book, I recommend doing a project or two. You can come up with an idea yourself, or you can follow one of the books that guide you through it.

For example:

  1. Learn Haskell by building a blog generator -> free, starts from 0 knowledge, and could even be used as the very first resource, instead of e.g. LYAH.
  2. The Simple Haskell Handbook -> not free, expects you to know the basics of Haskell already

Once you have more experience with projects, I would recommend re-reading your beginner book of choice. This time, you can skip the parts you already know and focus on what was confusing before. You will likely have a much easier time grasping those harder concepts.

p.s. If you are looking for a bit of extra motivation, check the blog post my teammate Shayne recently wrote about his journey with Haskell. He started in late 2021 and has already made huge progress!

Good luck with Haskell! If you have Haskell questions for me or the rest of the Wasp team, drop me a line at “martin” ++ “@” ++ concat [”wasp”, “-”, “lang”] <> “.dev” , or write to #haskell channel in Wasp-lang Discord server.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/09/05/dev-excuses-app-tutrial.html b/blog/2022/09/05/dev-excuses-app-tutrial.html index a59344b551..49e092a20a 100644 --- a/blog/2022/09/05/dev-excuses-app-tutrial.html +++ b/blog/2022/09/05/dev-excuses-app-tutrial.html @@ -19,13 +19,13 @@ - - + + -
-

Building an app to find an excuse for our sloppy work

· 8 min read

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!

Best excuse of all time

Best excuse of all time! Taken from here.

The requirements were unclear.​

We’ll use Michele Gerarduzzi’s open-source project. 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.

Final result

There’s an issue with the third party library.​

Setting up a backbone for the project is the most frustrating part of building any application.

We are installing dependencies, tying up the back-end and front-end, setting up a database, managing connection strings, and so on. Avoiding this part will save us a ton of time and effort. So let’s find ourselves an excuse to skip the initial project setup.

Ideally – use a framework that will create a project infrastructure quickly with the best defaults so that we’ll focus on the business logic. A perfect candidate is Wasp. It’s an open-source, declarative DSL for building web apps in React and Node.js with no boilerplate

How it works: developer starts from a single config file that specifies the app architecture. Routes, CRUD API, auth, and so on. Then adds React/Node.js code for the specific business logic. Behind the scenes, Wasp compiler will produce the entire source code of the app - back-end, front-end, deployment template, database migrations and everything else you’ve used to have in any other full-stack app.

Wasp architecture

So let’s jump right in.

Maybe something's wrong with the environment.​

Wasp intentionally works with the LTS Node.js version since it guarantees stability and active maintenance. As for now, it’s Node 16 and NPM 8. If you need another Node version for some other project – there’s a possibility to use NVM to manage multiple Node versions on your computer at the same time.

Installing Wasp on Linux (for Mac/Windows, please check the docs):

curl -sSL https://get.wasp-lang.dev/installer.sh | sh

Now let’s create a new web app 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! 🥳 We’ve built and run a NodeJS + React application. And 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.

Initial page

That worked perfectly when I developed it.​

1) Let’s add some additional configuration to our main.wasp file. So it will look like this:

main.wasp | Defining Excuse entity, queries and action

// Main declaration, defines a new web app.
app ItWaspsOnMyMachine {
  // Wasp compiler configuration
  wasp: {
    version: "^0.6.0"
  },

  // 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 `src/client/MainPage.js` as a default export.
page MainPage {                                             
  component: import Main from "@client/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 "@server/queries.js",
  entities: [Excuse]
}

// Query declaration to get all excuses
query getAllSavedExcuses {                                  
  fn: import { getAllSavedExcuses } from "@server/queries.js",
  entities: [Excuse]
}

// Action to save current excuse
action saveExcuse {                                         
  fn: import { saveExcuse } from "@server/actions.js",
  entities: [Excuse]
}

We’ve added Tailwind to make our UI more pretty and Axios for making API requests.

Also, we’ve declared 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. So let’s proceed with queries/actions.

2) Create two files: “actions.js” and “queries.js” in the src/server folder.

src/server/actions.js | Defining an action
export const saveExcuse = async (excuse, context) => {
  return context.entities.Excuse.create({
    data: { text: excuse.text }
  })
}
src/server/queries.js | Defining queries
import axios from 'axios';

export const getExcuse = async () => {
  const response = await axios.get('https://api.devexcus.es/')
  return response.data
}

export const getAllSavedExcuses = async (_args, context) => {
  return context.entities.Excuse.findMany()
}

Let’s add saveExcuse() action to our actions.js file. This action will save the text of our excuse to the database. Then let’s 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.

That’s it! We finished our back-end. 🎉 Now, let’s use those queries/actions on our UI.

3) Let’s erase everything we had in the MainPage.js file and substitute it with our new UI.

src/client/MainPage.js | Updating the UI
import React, { useState } from 'react'
import { useQuery } from '@wasp/queries'
import getExcuse from '@wasp/queries/getExcuse'
import getAllSavedExcuses from '@wasp/queries/getAllSavedExcuses'
import saveExcuse from '@wasp/actions/saveExcuse'

const MainPage = () => {
  const [currentExcuse, setCurrentExcuse] = useState({ text: "" })
  const { data: excuses } = useQuery(getAllSavedExcuses)

  const handleGetExcuse = async () => {
    try {
      setCurrentExcuse(await getExcuse())
    } catch (err) {
      window.alert('Error while getting the excuse: ' + err.message)
    }
  }

  const handleSaveExcuse = async () => {
    if (currentExcuse.text) {
      try {
        await saveExcuse(currentExcuse)
      } catch (err) {
        window.alert('Error while saving the excuse: ' + err.message)
      }
    }
  }

  return (
    <div className="grid grid-cols-2 text-3xl">
      <div>
          <button onClick={handleGetExcuse} className="mx-2 my-1 p-2 bg-blue-600 hover:bg-blue-400 text-white rounded"> Get excuse </button>
          <button onClick={handleSaveExcuse} className="mx-2 my-1 p-2 bg-blue-600 hover:bg-blue-400 text-white rounded"> Save excuse </button>
        <Excuse excuse={currentExcuse} />
      </div>
      <div>
        <div className="px-6 py-2 bg-blue-600 text-white"> Saved excuses: </div>
        {excuses && <ExcuseList excuses={excuses} />}
      </div>
    </div>
  )
}

const ExcuseList = (props) => { 
  return props.excuses?.length ?  props.excuses.map((excuse, idx) => <Excuse excuse={excuse} key={idx} />) : 'No saved excuses'
}

const Excuse = ({ excuse }) => {
  return (
    <div className="px-6 py-2">
      {excuse.text}
    </div>
  )
}

export default MainPage

Our page consists of three components. MainPage, ExcuseList and Excuse. It may seem at first that this file is pretty complex. It’s not, so let’s look a bit closer.

Excuse is just a div with an excuse text, ExcuseList checks if there are any excuses. If the list is empty – show a message No saved excuses. In other case – excuses will be displayed.

MainPage contains info about the current excuses and the list of already saved excuses. Two buttons click handlers handleGetExcuse and handleSaveExcuse. Plus, the markup itself with some Tailwind flavor.

4) 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

Final empty result

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:

Final result

It would have taken twice as long to build it properly.​

Now we can think of some additional improvements. For example:

  • 1) Add a unique constraint to Entity’s ID so we won’t be able to save duplicated excuses.
  • 2) Add exceptions and edge cases handling.
  • 3) Make the markup prettier.
  • 4) 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.

Box of excuses for the win!

We are in Beta (try it out)! → Join our community → Work with us

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Building an app to find an excuse for our sloppy work

· 8 min read

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!

Best excuse of all time

Best excuse of all time! Taken from here.

The requirements were unclear.​

We’ll use Michele Gerarduzzi’s open-source project. 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.

Final result

There’s an issue with the third party library.​

Setting up a backbone for the project is the most frustrating part of building any application.

We are installing dependencies, tying up the back-end and front-end, setting up a database, managing connection strings, and so on. Avoiding this part will save us a ton of time and effort. So let’s find ourselves an excuse to skip the initial project setup.

Ideally – use a framework that will create a project infrastructure quickly with the best defaults so that we’ll focus on the business logic. A perfect candidate is Wasp. It’s an open-source, declarative DSL for building web apps in React and Node.js with no boilerplate

How it works: developer starts from a single config file that specifies the app architecture. Routes, CRUD API, auth, and so on. Then adds React/Node.js code for the specific business logic. Behind the scenes, Wasp compiler will produce the entire source code of the app - back-end, front-end, deployment template, database migrations and everything else you’ve used to have in any other full-stack app.

Wasp architecture

So let’s jump right in.

Maybe something's wrong with the environment.​

Wasp intentionally works with the LTS Node.js version since it guarantees stability and active maintenance. As for now, it’s Node 16 and NPM 8. If you need another Node version for some other project – there’s a possibility to use NVM to manage multiple Node versions on your computer at the same time.

Installing Wasp on Linux (for Mac/Windows, please check the docs):

curl -sSL https://get.wasp-lang.dev/installer.sh | sh

Now let’s create a new web app 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! 🥳 We’ve built and run a NodeJS + React application. And 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.

Initial page

That worked perfectly when I developed it.​

1) Let’s add some additional configuration to our main.wasp file. So it will look like this:

main.wasp | Defining Excuse entity, queries and action

// Main declaration, defines a new web app.
app ItWaspsOnMyMachine {
  // Wasp compiler configuration
  wasp: {
    version: "^0.6.0"
  },

  // 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 `src/client/MainPage.js` as a default export.
page MainPage {                                             
  component: import Main from "@client/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 "@server/queries.js",
  entities: [Excuse]
}

// Query declaration to get all excuses
query getAllSavedExcuses {                                  
  fn: import { getAllSavedExcuses } from "@server/queries.js",
  entities: [Excuse]
}

// Action to save current excuse
action saveExcuse {                                         
  fn: import { saveExcuse } from "@server/actions.js",
  entities: [Excuse]
}

We’ve added Tailwind to make our UI more pretty and Axios for making API requests.

Also, we’ve declared 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. So let’s proceed with queries/actions.

2) Create two files: “actions.js” and “queries.js” in the src/server folder.

src/server/actions.js | Defining an action
export const saveExcuse = async (excuse, context) => {
  return context.entities.Excuse.create({
    data: { text: excuse.text }
  })
}
src/server/queries.js | Defining queries
import axios from 'axios';

export const getExcuse = async () => {
  const response = await axios.get('https://api.devexcus.es/')
  return response.data
}

export const getAllSavedExcuses = async (_args, context) => {
  return context.entities.Excuse.findMany()
}

Let’s add saveExcuse() action to our actions.js file. This action will save the text of our excuse to the database. Then let’s 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.

That’s it! We finished our back-end. 🎉 Now, let’s use those queries/actions on our UI.

3) Let’s erase everything we had in the MainPage.js file and substitute it with our new UI.

src/client/MainPage.js | Updating the UI
import React, { useState } from 'react'
import { useQuery } from '@wasp/queries'
import getExcuse from '@wasp/queries/getExcuse'
import getAllSavedExcuses from '@wasp/queries/getAllSavedExcuses'
import saveExcuse from '@wasp/actions/saveExcuse'

const MainPage = () => {
  const [currentExcuse, setCurrentExcuse] = useState({ text: "" })
  const { data: excuses } = useQuery(getAllSavedExcuses)

  const handleGetExcuse = async () => {
    try {
      setCurrentExcuse(await getExcuse())
    } catch (err) {
      window.alert('Error while getting the excuse: ' + err.message)
    }
  }

  const handleSaveExcuse = async () => {
    if (currentExcuse.text) {
      try {
        await saveExcuse(currentExcuse)
      } catch (err) {
        window.alert('Error while saving the excuse: ' + err.message)
      }
    }
  }

  return (
    <div className="grid grid-cols-2 text-3xl">
      <div>
          <button onClick={handleGetExcuse} className="mx-2 my-1 p-2 bg-blue-600 hover:bg-blue-400 text-white rounded"> Get excuse </button>
          <button onClick={handleSaveExcuse} className="mx-2 my-1 p-2 bg-blue-600 hover:bg-blue-400 text-white rounded"> Save excuse </button>
        <Excuse excuse={currentExcuse} />
      </div>
      <div>
        <div className="px-6 py-2 bg-blue-600 text-white"> Saved excuses: </div>
        {excuses && <ExcuseList excuses={excuses} />}
      </div>
    </div>
  )
}

const ExcuseList = (props) => { 
  return props.excuses?.length ?  props.excuses.map((excuse, idx) => <Excuse excuse={excuse} key={idx} />) : 'No saved excuses'
}

const Excuse = ({ excuse }) => {
  return (
    <div className="px-6 py-2">
      {excuse.text}
    </div>
  )
}

export default MainPage

Our page consists of three components. MainPage, ExcuseList and Excuse. It may seem at first that this file is pretty complex. It’s not, so let’s look a bit closer.

Excuse is just a div with an excuse text, ExcuseList checks if there are any excuses. If the list is empty – show a message No saved excuses. In other case – excuses will be displayed.

MainPage contains info about the current excuses and the list of already saved excuses. Two buttons click handlers handleGetExcuse and handleSaveExcuse. Plus, the markup itself with some Tailwind flavor.

4) 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

Final empty result

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:

Final result

It would have taken twice as long to build it properly.​

Now we can think of some additional improvements. For example:

  • 1) Add a unique constraint to Entity’s ID so we won’t be able to save duplicated excuses.
  • 2) Add exceptions and edge cases handling.
  • 3) Make the markup prettier.
  • 4) 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.

Box of excuses for the win!

We are in Beta (try it out)! → Join our community → Work with us

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/09/29/journey-to-1000-gh-stars.html b/blog/2022/09/29/journey-to-1000-gh-stars.html index 4d9e2a8d81..f70f8a5095 100644 --- a/blog/2022/09/29/journey-to-1000-gh-stars.html +++ b/blog/2022/09/29/journey-to-1000-gh-stars.html @@ -19,13 +19,13 @@ - - + + -
-

How Wasp reached 1,000 stars on GitHub (detailed stats & timeline)

· 12 min read
Matija Sosic

Wasp is an open-source configuration language for building full-stack web apps that integrates with React & Node.js. We launched first prototype 2 years ago, currently are at 1.9k stars on GitHub and will be releasing Beta in the coming months.

It was very hard for us to find and be able to learn from early inception stories of successful OSS projects and that's why we want to share what it looked like for Wasp.

1k stars chart

Before the stars: Is this really a problem? (1 year)​

My co-founder and twin brother Martin and I got an initial idea for Wasp in 2018, while developing a web platform for running bioinformatics analysis in the cloud for one London-based startup.

It was our third or fourth time creating a full-stack app from scratch with the latest & hottest stack. This time, it was React/Node.js; for our previous projects, we went through PHP/Java/Node.js on the back-end and jQuery/Backbone/Angular on the front-end. Because Martin and I felt we were spending a lot of time relearning how to use the latest stack just to build the same features all over again (auth, CRUD, forms, async jobs, etc.), we asked ourselves: Why not abstract these common functionalities in a stack-agnostic, higher-level language (like e.g. SQL does for databases) to never reimplement them again?

Before we jumped into coding, we wanted to make sure this is a problem that actually exists and that we understand it well (enough). In our previous startup we found Customer Development (aka talking to users) extremely helpful, so we decided to do it again for Wasp.

In a month or so we conducted 25 problem interviews, probing around “What is your biggest challenge with web app development?” After we compiled the results, we identified the following four problems as the most significant ones and decided to focus on them in our v1:

  • It is hard to quickly start a new web app and make sure the best practices are being followed.
  • There is a lot of duplication/boilerplate in managing the state across front-end, back-end, and the database.
  • A lot of common features are re-implemented for every new app.
  • Developers are overwhelmed by the increasing tool complexity and don't want to be responsible for managing it.

We also clustered the answers we got by topics, so we could dive deeper and identify the areas that got the most attention:

Start and setup of a web app - problems
Interviewee problems regarding starting and setting up a new web app.

The reason why we stopped at 25 was that the answers started repeating themselves. We felt that we identified the initial patterns and were ready to move on.

0-180 ⭐️: First Contact (7 months)​

After confirming and clarifying the problem with other developers, Martin and I felt we finally deserved to do some coding. (Ok, I admit, we had actually already started, but the interviews made us feel better about it 😀). We created a new repo on GitHub and started setting up the tooling & playing around with the concept.

For the next couple of months, we treated Wasp as a side project/experiment and didn’t do any marketing. However, we were well aware of how crucial external feedback is. So, once we built a very rudimentary code generation functionality, we also created a project page that we could share with others to explain what we’re working on and ask for feedback.

At that point, we came up with the first “real” name for Wasp - STIC: Specification To Implementation Compiler, as the big vision for Wasp was to be a stack-agnostic, specification language from which we could generate the actual code in e.g. React & Node.js or even some other stack.

STIC - first project page
Our first page for Wasp! Not the best at explaining what Wasp does, though.

Baby steps on Reddit and Hacker News​

Our preferred way of distributing STIC project page was through relevant subreddits - r/webdev, r/coding, r/javascript, r/Haskell, r/ProgrammingLanguages, ….

This was the first Reddit post we’ve ever made about Wasp:

First Wasp post on Reddit
Our first Reddit post! We managed to get some feedback before we got banned.

One important thing we learned is that Reddit doesn’t like self-promotion. Sometimes, even if you’re only asking for feedback, the mods (and bots) will see it as self-promo and ban your post. It depends a lot on the mods, though. Reaching out to them and asking for explanation sometimes helps, but not very often. All subreddits have their own rules and guidelines that describe when or how it is OK to post about your project (e.g., /r/webdev has “Showoff Saturdays”), and we tried to follow them as best as we could.

After Reddit, we also launched on HN. This was our first ever launch there! We scored 20 points and received a few motivating comments:

First Wasp post on Reddit

Listening to users​

Martin and I also followed up with the people we had previously interviewed about their problems in web dev. We showed them STIC project page and asked for comments. From all the feedback we captured, we identified the following issues:

  • Developers were not familiar with a term “DSL.” Almost all of us use a DSL on a daily basis (e.g., SQL, HCL (Terraform), HTML), but it’s not a popular term.
  • Developers feared learning a new programming language. Although our goal was never to replace e.g. Java or Typescript but to make Wasp work alongside it, we discovered that we had failed to communicate it well. Our messaging made developers feel they have to drop all their previous knowledge and start from scratch if they want to use Wasp.
  • Nobody could try Wasp yet + there wasn’t any documentation besides the project page. Our code was public, but we didn’t have a build/distribution system yet. Only a devoted Haskell developer could build it from the source. This made it hard for developers to buy into the high-level vision, as there was nothing they could hold onto. Web frameworks/languages are very “tactile” — it’s hard to judge one without trying it out.

180-300 ⭐️ : Anybody can try Wasp out + Docs = Alpha! (3 months)​

After processing this feedback, we realized that the next step for us was to get Wasp into the condition where developers can easily try it out without needing any extra knowledge or facing the trouble of compiling from the source. That meant polishing things a bit, adding a few crucial features, and writing our first documentation, so that users would know how to use it.

To write our docs, we picked Docusaurus — an OSS writing platform made by Facebook. We saw several other OSS projects using it for their docs + its ability to import React in your markdown was amazing. Docusaurus gave us a lot of initial structure, design and features (e.g., search), saving us from reinventing the wheel.

First Wasp docs
Martin made sure to add a huge Alpha warning sign :D

Our M.O. at the time was to focus pretty much exclusively on one thing, either development or community. Since Wasp team consisted of only Martin and me, it was really hard to do multiple things at once. After the docs were out and Wasp was ready to be easily downloaded, we called this version “Alpha” and switched once again into the “community” mode.

300-570 ⭐️ : Big break on Reddit and Product Hunt (2 months)​

Once Alpha was out, we launched again on HackerNews and drew a bit of attention (34 upvotes and 3 comments). However, that was little compared to our Reddit launches, where we scored 263 upvotes on r/javascript and 365 upvotes on r/reactjs:

Big break on Reddit
They love me! [insert Tobey Maguire as Spiderman]

Compared to the volume of attention and feedback we’ve been previously receiving, this was a big surprise for us! Here are some of the changes in messaging that we made for the Reddit launches:

  • Put prefix “declarative” in front of the “language” to convey that it’s not a regular programming language like Python or Javascript but rather something much more lightweight and specialized.
  • Emphasized that Wasp is not a standalone language that will replace your current stack but rather a “glue” between your React & Node.js code, allowing you to keep using your favourite stack.
  • Focused on the benefits like “less boilerplate,” which is a well known pain in web development.
Docs made the difference

Once we added the docs, we noticed a peculiar thing: developers became much less trigger-happy to criticize the project, especially in a non-constructive way. Our feeling was the majority of developers who were checking Wasp out still didn’t read the docs in detail (or at all), but the sheer existence of them made them feel there is more content they should go through before passing the final judgment.

Winning #1 Product of The Day on Product Hunt​

After HN and Reddit, we continued with the “Alpha launch” mindset and set ourselves to launch Wasp on Product Hunt. It was our first time ever launching on PH, so we didn’t know what to expect. We googled some advice, did maybe a week of preparation (i.e., wrote the copy, asked a few friends to share their experiences with Wasp once we’re live), and that was it.

We launched Wasp on PH on Dec 6, 2020 and it ended up as Product of the day! That gave us a boost in stars and overall traction. Another benefit of PH was that Wasp also ended up in their daily newsletter, which supposedly has over a million subscribers. All this gave us quite a boost and visibility increase.

Product Hunt launch

570-1000 ⭐️ : Wasp joins YC + “Official” HN launch (2.5 months)​

Soon after Product Hunt, Wasp joined Y Combinator for their W21 batch. We had applied two times before and always made it to the interviews, but did not get in. This time, the traction tipped the scales in our favour. (You can read more about our journey to YC here.)

For the first month of YC, there was a lot of admin and setup work to deal with alongside the regular program. That added a third dimension to our existing two areas of effort. Once we went past that, we could again put more focus on product and community development.

Our next milestone was to launch Wasp on Hacker News, but this time “officially” as a YC-backed company. Hacker News provides a lot of good tips on how to successfully launch and 80% of the advice applies even if your product isn’t backed by YC. I wish I had known about it before. The gist of the advice is to write in a clear and succinct way and to avoid buzzwords, superlatives, and salesy tone above all. Consider HN readers as your peers and explain what you do in a way you would talk to a friend over a drink. It really works that way.

We went through the several iterations of the text, sweated over how it’s gonna go, and when the day finally came — we launched! It went beyond all our expectations. With 222 points and 79 comments, our HN launch was one of the most successful launches (#9) out of 300+ companies in the W21 batch. Many developers and VCs that checked our launch afterwards were surprised how much positive feedback Wasp received, especially given how honest and direct HN audience can be.

HN launch brought us about 200 stars right away, and the rest came in the following weeks. As it was February and the YC program was nearing its end, we needed to shift gears again and focus on fundraising. This put all the other efforts on the back burner. (You can read about our fundraising learnings from 250+ meetings in 98 days here.) But the interest of the community remained and even without much activity from our side they kept coming and trying Wasp out.

YC HN launch

Conclusion: understanding users > number of stars​

Our primary goal was never to reach X stars, but rather to understand how we can make Wasp more helpful so that developers would want to use it for their projects. As you could read above, even well before we started a repository we made sure to talk to developers and learn about their problems.

We also kept continually improving how we present Wasp - had we not pivoted our message from “Wasp is a new programming language” to “Wasp is a simple config language that works alongside React & Node.js” we wouldn’t have been where we are today.

On the other hand, stars have become an unofficial “currency” of GitHub and developers and VCs alike consider it when evaluating a project. They shouldn’t be disregarded and you should make it easy for users who like your product to express their support by starring your repo (like I’m doing right here), but that should always be a second order of concern.

Good luck!​

I hope you found this helpful and that we shed some light on how things can look like in the early stages of an OSS project. Also, keep in mind this was our singular experience and that every story is different, so take everything with a grain of salt and pick only what makes sense for you and your product.

We wish you the best of luck and feel free to reach out if you'll have any questions!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

How Wasp reached 1,000 stars on GitHub (detailed stats & timeline)

· 12 min read
Matija Sosic

Wasp is an open-source configuration language for building full-stack web apps that integrates with React & Node.js. We launched first prototype 2 years ago, currently are at 1.9k stars on GitHub and will be releasing Beta in the coming months.

It was very hard for us to find and be able to learn from early inception stories of successful OSS projects and that's why we want to share what it looked like for Wasp.

1k stars chart

Before the stars: Is this really a problem? (1 year)​

My co-founder and twin brother Martin and I got an initial idea for Wasp in 2018, while developing a web platform for running bioinformatics analysis in the cloud for one London-based startup.

It was our third or fourth time creating a full-stack app from scratch with the latest & hottest stack. This time, it was React/Node.js; for our previous projects, we went through PHP/Java/Node.js on the back-end and jQuery/Backbone/Angular on the front-end. Because Martin and I felt we were spending a lot of time relearning how to use the latest stack just to build the same features all over again (auth, CRUD, forms, async jobs, etc.), we asked ourselves: Why not abstract these common functionalities in a stack-agnostic, higher-level language (like e.g. SQL does for databases) to never reimplement them again?

Before we jumped into coding, we wanted to make sure this is a problem that actually exists and that we understand it well (enough). In our previous startup we found Customer Development (aka talking to users) extremely helpful, so we decided to do it again for Wasp.

In a month or so we conducted 25 problem interviews, probing around “What is your biggest challenge with web app development?” After we compiled the results, we identified the following four problems as the most significant ones and decided to focus on them in our v1:

  • It is hard to quickly start a new web app and make sure the best practices are being followed.
  • There is a lot of duplication/boilerplate in managing the state across front-end, back-end, and the database.
  • A lot of common features are re-implemented for every new app.
  • Developers are overwhelmed by the increasing tool complexity and don't want to be responsible for managing it.

We also clustered the answers we got by topics, so we could dive deeper and identify the areas that got the most attention:

Start and setup of a web app - problems
Interviewee problems regarding starting and setting up a new web app.

The reason why we stopped at 25 was that the answers started repeating themselves. We felt that we identified the initial patterns and were ready to move on.

0-180 ⭐️: First Contact (7 months)​

After confirming and clarifying the problem with other developers, Martin and I felt we finally deserved to do some coding. (Ok, I admit, we had actually already started, but the interviews made us feel better about it 😀). We created a new repo on GitHub and started setting up the tooling & playing around with the concept.

For the next couple of months, we treated Wasp as a side project/experiment and didn’t do any marketing. However, we were well aware of how crucial external feedback is. So, once we built a very rudimentary code generation functionality, we also created a project page that we could share with others to explain what we’re working on and ask for feedback.

At that point, we came up with the first “real” name for Wasp - STIC: Specification To Implementation Compiler, as the big vision for Wasp was to be a stack-agnostic, specification language from which we could generate the actual code in e.g. React & Node.js or even some other stack.

STIC - first project page
Our first page for Wasp! Not the best at explaining what Wasp does, though.

Baby steps on Reddit and Hacker News​

Our preferred way of distributing STIC project page was through relevant subreddits - r/webdev, r/coding, r/javascript, r/Haskell, r/ProgrammingLanguages, ….

This was the first Reddit post we’ve ever made about Wasp:

First Wasp post on Reddit
Our first Reddit post! We managed to get some feedback before we got banned.

One important thing we learned is that Reddit doesn’t like self-promotion. Sometimes, even if you’re only asking for feedback, the mods (and bots) will see it as self-promo and ban your post. It depends a lot on the mods, though. Reaching out to them and asking for explanation sometimes helps, but not very often. All subreddits have their own rules and guidelines that describe when or how it is OK to post about your project (e.g., /r/webdev has “Showoff Saturdays”), and we tried to follow them as best as we could.

After Reddit, we also launched on HN. This was our first ever launch there! We scored 20 points and received a few motivating comments:

First Wasp post on Reddit

Listening to users​

Martin and I also followed up with the people we had previously interviewed about their problems in web dev. We showed them STIC project page and asked for comments. From all the feedback we captured, we identified the following issues:

  • Developers were not familiar with a term “DSL.” Almost all of us use a DSL on a daily basis (e.g., SQL, HCL (Terraform), HTML), but it’s not a popular term.
  • Developers feared learning a new programming language. Although our goal was never to replace e.g. Java or Typescript but to make Wasp work alongside it, we discovered that we had failed to communicate it well. Our messaging made developers feel they have to drop all their previous knowledge and start from scratch if they want to use Wasp.
  • Nobody could try Wasp yet + there wasn’t any documentation besides the project page. Our code was public, but we didn’t have a build/distribution system yet. Only a devoted Haskell developer could build it from the source. This made it hard for developers to buy into the high-level vision, as there was nothing they could hold onto. Web frameworks/languages are very “tactile” — it’s hard to judge one without trying it out.

180-300 ⭐️ : Anybody can try Wasp out + Docs = Alpha! (3 months)​

After processing this feedback, we realized that the next step for us was to get Wasp into the condition where developers can easily try it out without needing any extra knowledge or facing the trouble of compiling from the source. That meant polishing things a bit, adding a few crucial features, and writing our first documentation, so that users would know how to use it.

To write our docs, we picked Docusaurus — an OSS writing platform made by Facebook. We saw several other OSS projects using it for their docs + its ability to import React in your markdown was amazing. Docusaurus gave us a lot of initial structure, design and features (e.g., search), saving us from reinventing the wheel.

First Wasp docs
Martin made sure to add a huge Alpha warning sign :D

Our M.O. at the time was to focus pretty much exclusively on one thing, either development or community. Since Wasp team consisted of only Martin and me, it was really hard to do multiple things at once. After the docs were out and Wasp was ready to be easily downloaded, we called this version “Alpha” and switched once again into the “community” mode.

300-570 ⭐️ : Big break on Reddit and Product Hunt (2 months)​

Once Alpha was out, we launched again on HackerNews and drew a bit of attention (34 upvotes and 3 comments). However, that was little compared to our Reddit launches, where we scored 263 upvotes on r/javascript and 365 upvotes on r/reactjs:

Big break on Reddit
They love me! [insert Tobey Maguire as Spiderman]

Compared to the volume of attention and feedback we’ve been previously receiving, this was a big surprise for us! Here are some of the changes in messaging that we made for the Reddit launches:

  • Put prefix “declarative” in front of the “language” to convey that it’s not a regular programming language like Python or Javascript but rather something much more lightweight and specialized.
  • Emphasized that Wasp is not a standalone language that will replace your current stack but rather a “glue” between your React & Node.js code, allowing you to keep using your favourite stack.
  • Focused on the benefits like “less boilerplate,” which is a well known pain in web development.
Docs made the difference

Once we added the docs, we noticed a peculiar thing: developers became much less trigger-happy to criticize the project, especially in a non-constructive way. Our feeling was the majority of developers who were checking Wasp out still didn’t read the docs in detail (or at all), but the sheer existence of them made them feel there is more content they should go through before passing the final judgment.

Winning #1 Product of The Day on Product Hunt​

After HN and Reddit, we continued with the “Alpha launch” mindset and set ourselves to launch Wasp on Product Hunt. It was our first time ever launching on PH, so we didn’t know what to expect. We googled some advice, did maybe a week of preparation (i.e., wrote the copy, asked a few friends to share their experiences with Wasp once we’re live), and that was it.

We launched Wasp on PH on Dec 6, 2020 and it ended up as Product of the day! That gave us a boost in stars and overall traction. Another benefit of PH was that Wasp also ended up in their daily newsletter, which supposedly has over a million subscribers. All this gave us quite a boost and visibility increase.

Product Hunt launch

570-1000 ⭐️ : Wasp joins YC + “Official” HN launch (2.5 months)​

Soon after Product Hunt, Wasp joined Y Combinator for their W21 batch. We had applied two times before and always made it to the interviews, but did not get in. This time, the traction tipped the scales in our favour. (You can read more about our journey to YC here.)

For the first month of YC, there was a lot of admin and setup work to deal with alongside the regular program. That added a third dimension to our existing two areas of effort. Once we went past that, we could again put more focus on product and community development.

Our next milestone was to launch Wasp on Hacker News, but this time “officially” as a YC-backed company. Hacker News provides a lot of good tips on how to successfully launch and 80% of the advice applies even if your product isn’t backed by YC. I wish I had known about it before. The gist of the advice is to write in a clear and succinct way and to avoid buzzwords, superlatives, and salesy tone above all. Consider HN readers as your peers and explain what you do in a way you would talk to a friend over a drink. It really works that way.

We went through the several iterations of the text, sweated over how it’s gonna go, and when the day finally came — we launched! It went beyond all our expectations. With 222 points and 79 comments, our HN launch was one of the most successful launches (#9) out of 300+ companies in the W21 batch. Many developers and VCs that checked our launch afterwards were surprised how much positive feedback Wasp received, especially given how honest and direct HN audience can be.

HN launch brought us about 200 stars right away, and the rest came in the following weeks. As it was February and the YC program was nearing its end, we needed to shift gears again and focus on fundraising. This put all the other efforts on the back burner. (You can read about our fundraising learnings from 250+ meetings in 98 days here.) But the interest of the community remained and even without much activity from our side they kept coming and trying Wasp out.

YC HN launch

Conclusion: understanding users > number of stars​

Our primary goal was never to reach X stars, but rather to understand how we can make Wasp more helpful so that developers would want to use it for their projects. As you could read above, even well before we started a repository we made sure to talk to developers and learn about their problems.

We also kept continually improving how we present Wasp - had we not pivoted our message from “Wasp is a new programming language” to “Wasp is a simple config language that works alongside React & Node.js” we wouldn’t have been where we are today.

On the other hand, stars have become an unofficial “currency” of GitHub and developers and VCs alike consider it when evaluating a project. They shouldn’t be disregarded and you should make it easy for users who like your product to express their support by starring your repo (like I’m doing right here), but that should always be a second order of concern.

Good luck!​

I hope you found this helpful and that we shed some light on how things can look like in the early stages of an OSS project. Also, keep in mind this was our singular experience and that every story is different, so take everything with a grain of salt and pick only what makes sense for you and your product.

We wish you the best of luck and feel free to reach out if you'll have any questions!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/10/28/farnance-hackathon-winner.html b/blog/2022/10/28/farnance-hackathon-winner.html index 5f707118e2..c74063bf95 100644 --- a/blog/2022/10/28/farnance-hackathon-winner.html +++ b/blog/2022/10/28/farnance-hackathon-winner.html @@ -19,13 +19,13 @@ - - + + -
-

Farnance: How Julian built a SaaS for farmers with Wasp and won a hackathon!

· 4 min read
Matija Sosic

farnance hero shot

Julian LaNeve is an engineer and data scientist who currently works at Astronomer.io as a Product Manager. In his free time, he enjoys playing poker, chess and winning data science competitions.

His project, Farnance, is a SaaS marketplace that allows farmers to transform their production into a digital asset on blockchain. Julian and his team developed Farnance as a part of the London Business School’s annual hackathon HackLBS 2021, and ended up as winners among more than 250 participants competing for 6 prizes in total!

Read on to learn why Julian chose Wasp to develop and deploy Farnance and what parts he enjoyed the most.

Finding a perfect React & Node.js hackathon setup​

Julian had previous experiences with React and Node.js and loved that he could use JavaScript across the stack, but setting up a new project and making sure it uses all the latest packages (and then also figuring out how to deploy it) was always a pain. Since the hackathon only lasted for two days, he needed a quick way to get started but still have the freedom to use his favourite stack.

The power of one-line auth and No-API approach​

Julian first learned about Wasp when it launched on HN and decided it would be a perfect tool for his case. The whole app setup, across the full stack, is covered out-of-the-box, simply by typing wasp new farnance, and he is ready to start writing own React & Node.js code.

Except on the app setup, the team saved a ton of time by not needing to implement the authentication and a typical CRUD API, since it is covered by Wasp as well. They could also deploy everything for free on Heroku and Netlify in just a few steps, which was a perfect fit for a hackathon.

Julian's testimonial on Discord

Farnance is still running and you can try it out here! The source code is also publicly available, although note it is running on older version of Wasp so some things are a bit different.

Spend more time developing features and less time reinventing the wheel​

Julian was amazed by how fast he was able to get Farnance of the ground and share a working web app with the users! He decided to go with Google's material-ui for an UI framework which gave his app an instant professional look, although they didn’t have a dedicated designer on the team.

With all the common web app features (setup, auth, CRUD API) being taken care of by Wasp out-of-the-box they could invest all the time saved in developing and refining their unique features which in the end brought them victory!

I’ve done plenty of hackathons before where I’ve built small SaaS apps, and there’s just so much time wasted setting up common utilities - stuff like user management, databases, routing, etc. Wasp handled all that for me and let me build out our web app in record time

— Julian LaNeve - Farnance

Farnance's dashboard
Farnance dashboard in action!

Start quickly, but also scale without worries​

note

Heroku used to offer free apps under certain limits. However, as of November 28, 2022, they ended support for their free tier. https://blog.heroku.com/next-chapter

As such, we have updated our Deployment docs with new recommendations: https://wasp-lang.dev/docs/deploying

Since Wasp compiler generates a full-stack React & Node.js app under the hood, there aren’t any technical limitations to scaling Julian’s app as it grows and gets more users in the future. By running wasp build inside a project folder, developers gets both frontend files and a Dockerfile for the backend, which can then be deployed as any regular web app to the platform of your choice.

Wasp provides step-by step instructions on how to do it with Netlify and Fly.io for free, but we plan to add even more examples and more integrated deployment experience in the coming releases!

Deploying the wasp app was incredibly easy - I didn’t have time to stand up full infrastructure in the 2 day hackathon and don’t have an infra/devops background, but I had something running on Netlify within an hour. Other projects at the hackathon struggled to do this, and putting access in the hands of the judges certainly helped get us 1st place.

— Julian LaNeve - Farnance

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Farnance: How Julian built a SaaS for farmers with Wasp and won a hackathon!

· 4 min read
Matija Sosic

farnance hero shot

Julian LaNeve is an engineer and data scientist who currently works at Astronomer.io as a Product Manager. In his free time, he enjoys playing poker, chess and winning data science competitions.

His project, Farnance, is a SaaS marketplace that allows farmers to transform their production into a digital asset on blockchain. Julian and his team developed Farnance as a part of the London Business School’s annual hackathon HackLBS 2021, and ended up as winners among more than 250 participants competing for 6 prizes in total!

Read on to learn why Julian chose Wasp to develop and deploy Farnance and what parts he enjoyed the most.

Finding a perfect React & Node.js hackathon setup​

Julian had previous experiences with React and Node.js and loved that he could use JavaScript across the stack, but setting up a new project and making sure it uses all the latest packages (and then also figuring out how to deploy it) was always a pain. Since the hackathon only lasted for two days, he needed a quick way to get started but still have the freedom to use his favourite stack.

The power of one-line auth and No-API approach​

Julian first learned about Wasp when it launched on HN and decided it would be a perfect tool for his case. The whole app setup, across the full stack, is covered out-of-the-box, simply by typing wasp new farnance, and he is ready to start writing own React & Node.js code.

Except on the app setup, the team saved a ton of time by not needing to implement the authentication and a typical CRUD API, since it is covered by Wasp as well. They could also deploy everything for free on Heroku and Netlify in just a few steps, which was a perfect fit for a hackathon.

Julian's testimonial on Discord

Farnance is still running and you can try it out here! The source code is also publicly available, although note it is running on older version of Wasp so some things are a bit different.

Spend more time developing features and less time reinventing the wheel​

Julian was amazed by how fast he was able to get Farnance of the ground and share a working web app with the users! He decided to go with Google's material-ui for an UI framework which gave his app an instant professional look, although they didn’t have a dedicated designer on the team.

With all the common web app features (setup, auth, CRUD API) being taken care of by Wasp out-of-the-box they could invest all the time saved in developing and refining their unique features which in the end brought them victory!

I’ve done plenty of hackathons before where I’ve built small SaaS apps, and there’s just so much time wasted setting up common utilities - stuff like user management, databases, routing, etc. Wasp handled all that for me and let me build out our web app in record time

— Julian LaNeve - Farnance

Farnance's dashboard
Farnance dashboard in action!

Start quickly, but also scale without worries​

note

Heroku used to offer free apps under certain limits. However, as of November 28, 2022, they ended support for their free tier. https://blog.heroku.com/next-chapter

As such, we have updated our Deployment docs with new recommendations: https://wasp-lang.dev/docs/deploying

Since Wasp compiler generates a full-stack React & Node.js app under the hood, there aren’t any technical limitations to scaling Julian’s app as it grows and gets more users in the future. By running wasp build inside a project folder, developers gets both frontend files and a Dockerfile for the backend, which can then be deployed as any regular web app to the platform of your choice.

Wasp provides step-by step instructions on how to do it with Netlify and Fly.io for free, but we plan to add even more examples and more integrated deployment experience in the coming releases!

Deploying the wasp app was incredibly easy - I didn’t have time to stand up full infrastructure in the 2 day hackathon and don’t have an infra/devops background, but I had something running on Netlify within an hour. Other projects at the hackathon struggled to do this, and putting access in the hands of the judges certainly helped get us 1st place.

— Julian LaNeve - Farnance

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/11/15/auth-feature-announcement.html b/blog/2022/11/15/auth-feature-announcement.html index eac029f144..eb6bbfe95e 100644 --- a/blog/2022/11/15/auth-feature-announcement.html +++ b/blog/2022/11/15/auth-feature-announcement.html @@ -19,13 +19,13 @@ - - + + -
-

Feature Announcement - New auth method (Google)

· 4 min read
Shayne Czyzewski

No login for you!

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Prologue​

We've all been there. Your app needs to support user authentication with social login, and you must now decide what to do next. Should you eschew the collective experience and wisdom of the crowd and YOLO it by rolling your own, praying you don't get pwned in prod? "Nah, I just ate some week-old sushi and can't take another risk that big anytime soon.", you rightly think.

Ok, surely you can just use a library, right? Open source software, baby! "Hmm, seems Library X, Y, and Z are all somewhat used, each with their pros/cons, nuances, and integration pain points. Oh wait, there are tutorials for each... but each says how hard they are to correctly set up and use. I scoped this feature for one day, not a one-week hair-pulling adventure (Dang scrum! Who likes it anyways? Oh yeah, PMs do. Dang PMs!)." Ok, something else. You need to brainstorm. You instead start to surf Twitter and see an ad for some unicorn auth startup.

Eureka, you can go with a third-party SaaS offering! "We shouldn't have to pay for a while (I think? hope!), and it's just another dependency, no biggie... #microservices, right?" "But what about outages, data privacy, mapping users between systems, and all that implicit trust you are placing in them?" you think. "What happens when Elon buys them next?" You gasp as if you walked by a Patagonia vest covered in that hot new Burnt Hair cologne.

"All I want is username and password auth with Google login support, why is that so hard in 2022?!? I miss Basic HTTP auth headers. I think I'll move off the grid and become a woodworker."

Easy auth setup in Wasp​

Wasp helps that dev by taking care of the entire auth setup process out of the box. Adding support for username and password auth, plus Google login, is super quick and easy for Wasp apps. We think this makes adding auth fast and convenient, with no external dependencies or frustrating manual configuration. Here’s how it works:

Step 1 - Add the appropriate models​

We need to store user info and the external mapping association for social logins. Here is an example you can start from and add new fields to:

./main.wasp
entity User {=psl
    id                        Int           @id @default(autoincrement())
    username                  String        @unique
    password                  String
    externalAuthAssociations  SocialLogin[]
psl=}

entity SocialLogin {=psl
  id          Int       @id @default(autoincrement())
  provider    String
  providerId  String
  user        User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  userId      Int
  createdAt   DateTime  @default(now())
  @@unique([provider, providerId, userId])
psl=}

Step 2 - Update app.auth to use these items​

./main.wasp
app authExample {
  // ...
  auth: {
    userEntity: User,
    externalAuthEntity: SocialLogin,
    methods: {
      usernameAndPassword: {},
      google: {}
    },
    onAuthFailedRedirectTo: "/login"
  }
}

Step 3 - Get Google credentials and add environment variables​

Follow the Google setup guide here and add the environment variables to your .env.server file.

Step 4 - Make use of the Google login button in your Login page component​

./src/client/auth/Login.js
import React from 'react'
import { Link } from 'react-router-dom'

import { SignInButton as GoogleSignInButton } from '@wasp/auth/helpers/Google'
import LoginForm from '@wasp/auth/forms/Login'

const Login = () => {
  return (
    <div>
      <div>
        <LoginForm/>
      </div>
      <div>
        I don't have an account yet (<Link to="/signup">go to signup</Link>).
      </div>
      <div>
        <GoogleSignInButton/>
      </div>
    </div>
  )
}

export default Login

Step 5 - Run the app!​

Epilogue​

No need to move off the grid out of frustration when adding authentication and social login to your web app. Here is a complete, minimal example if you want to jump right in, and here are the full docs for more info. With just a few simple steps above, we've added authentication with best practices baked into our app so we can move on to solving problems that add value to our users!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Feature Announcement - New auth method (Google)

· 4 min read
Shayne Czyzewski

No login for you!

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

Prologue​

We've all been there. Your app needs to support user authentication with social login, and you must now decide what to do next. Should you eschew the collective experience and wisdom of the crowd and YOLO it by rolling your own, praying you don't get pwned in prod? "Nah, I just ate some week-old sushi and can't take another risk that big anytime soon.", you rightly think.

Ok, surely you can just use a library, right? Open source software, baby! "Hmm, seems Library X, Y, and Z are all somewhat used, each with their pros/cons, nuances, and integration pain points. Oh wait, there are tutorials for each... but each says how hard they are to correctly set up and use. I scoped this feature for one day, not a one-week hair-pulling adventure (Dang scrum! Who likes it anyways? Oh yeah, PMs do. Dang PMs!)." Ok, something else. You need to brainstorm. You instead start to surf Twitter and see an ad for some unicorn auth startup.

Eureka, you can go with a third-party SaaS offering! "We shouldn't have to pay for a while (I think? hope!), and it's just another dependency, no biggie... #microservices, right?" "But what about outages, data privacy, mapping users between systems, and all that implicit trust you are placing in them?" you think. "What happens when Elon buys them next?" You gasp as if you walked by a Patagonia vest covered in that hot new Burnt Hair cologne.

"All I want is username and password auth with Google login support, why is that so hard in 2022?!? I miss Basic HTTP auth headers. I think I'll move off the grid and become a woodworker."

Easy auth setup in Wasp​

Wasp helps that dev by taking care of the entire auth setup process out of the box. Adding support for username and password auth, plus Google login, is super quick and easy for Wasp apps. We think this makes adding auth fast and convenient, with no external dependencies or frustrating manual configuration. Here’s how it works:

Step 1 - Add the appropriate models​

We need to store user info and the external mapping association for social logins. Here is an example you can start from and add new fields to:

./main.wasp
entity User {=psl
    id                        Int           @id @default(autoincrement())
    username                  String        @unique
    password                  String
    externalAuthAssociations  SocialLogin[]
psl=}

entity SocialLogin {=psl
  id          Int       @id @default(autoincrement())
  provider    String
  providerId  String
  user        User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  userId      Int
  createdAt   DateTime  @default(now())
  @@unique([provider, providerId, userId])
psl=}

Step 2 - Update app.auth to use these items​

./main.wasp
app authExample {
  // ...
  auth: {
    userEntity: User,
    externalAuthEntity: SocialLogin,
    methods: {
      usernameAndPassword: {},
      google: {}
    },
    onAuthFailedRedirectTo: "/login"
  }
}

Step 3 - Get Google credentials and add environment variables​

Follow the Google setup guide here and add the environment variables to your .env.server file.

Step 4 - Make use of the Google login button in your Login page component​

./src/client/auth/Login.js
import React from 'react'
import { Link } from 'react-router-dom'

import { SignInButton as GoogleSignInButton } from '@wasp/auth/helpers/Google'
import LoginForm from '@wasp/auth/forms/Login'

const Login = () => {
  return (
    <div>
      <div>
        <LoginForm/>
      </div>
      <div>
        I don't have an account yet (<Link to="/signup">go to signup</Link>).
      </div>
      <div>
        <GoogleSignInButton/>
      </div>
    </div>
  )
}

export default Login

Step 5 - Run the app!​

Epilogue​

No need to move off the grid out of frustration when adding authentication and social login to your web app. Here is a complete, minimal example if you want to jump right in, and here are the full docs for more info. With just a few simple steps above, we've added authentication with best practices baked into our app so we can move on to solving problems that add value to our users!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/11/16/alpha-testing-program-post-mortem.html b/blog/2022/11/16/alpha-testing-program-post-mortem.html index 1254a3055a..aa97948ad1 100644 --- a/blog/2022/11/16/alpha-testing-program-post-mortem.html +++ b/blog/2022/11/16/alpha-testing-program-post-mortem.html @@ -19,13 +19,13 @@ - - + + -
-

Alpha Testing Program: post-mortem

· 7 min read
Matija Sosic

We are working on a new web framework that integrates with React & Node.js, and also happens to be a language. As you can probably imagine, it’s not easy to get people to use a new piece of technology, especially while still in Alpha. On the other hand, without users and their feedback, it’s impossible to know what to build.

That is why we ran Alpha Testing Program for Wasp - here is what we learned and what went both well and wrong along the way.

twitter DM - shared atp in swag groups

“Of course I know about Wasp! I just haven’t come around to trying it out yet.”​

Although we hit the front page of HN several times and are about to reach 2,000 stars on GitHub, there is still a big difference between a person starring a repo and actually sitting down and building something with it.

Talking to people, we realised a lot of them had heard of Wasp, thought it was a neat idea, but hadn’t tried it out. These were the main reasons:

  • having to find 30 mins to go through our Build a Todo App tutorial - “I'm busy now, but I’ll do it next week.”
  • building a bare-bones todo app is not that exciting
  • not having an idea what else to build
  • “the product is still in alpha, so I will bookmark it for later”

These are all obvious and understandable reasons. I must admit, I’m much the same — maybe even worse — when it comes to trying out something new/unproven. It just isn’t a priority, and without a push that will help me overcome all these objections, I usually don’t have an incentive to go through with it.

Having realised all that, we understood we needed to give people a reason to try Wasp out now, because that’s when we needed the feedback, not next week.

Welcome to Wasp Alpha Testing Program!​

The team
I was having a bit too much fun here, but Portal fans will understand.

We quickly put together an admissions page for alpha testers in Notion (you can see it here) and started sharing it around. To counter the hurdles we mentioned above, we time-boxed the program (”this is happening now and you have 48 hours to finish once you start”) and promised a t-shirt to everyone that goes through the tutorial and fills out the feedback form.

Apply to ATP - CTA
CTA from the admissions page

Soon, the first applications started trickling in! For each new applicant, we’d follow up with the instructions on how to successfully go through the Alpha Testing Program:

  • fill out intro form (years of experience, preferred stack, etc)
  • go through our “build a Todo app” tutorial
  • fill out the feedback form - what was good, what was bad etc.

Timeboxing
People were really respectful of this deadline and would politely ask to extend it in case they couldn’t make it.

But, soon after I got the following message on Twitter:

twitter DM - shared atp in swag groups

We got really scared that we would get a ton of folks putting in minimal effort while trying Wasp out just to get the free swag, leaving us empty-handed and having learned nothing! On the other hand, we didn’t have much choice since we didn’t define the “minimum required quality” of feedback in advance.

Luckily, it wasn’t the problem in the end, even the opposite -- we did get a surge of applications, but only a portion of them finished the program and the ones that did left really high-quality feedback!

How it went - test profile & feedback​

Tester profile​

We received 210 applications and 53 out of those completed the program — 25% completion rate.

We also surveyed applicants about their preferred stack, years of programming experience, etc:

Intro survey - tester profile
Yep, we like puns.

The feedback​

The feedback form evaluated testers’ overall experience with Wasp. We asked them what they found to be the best and worst parts of working with Wasp, as well as about the next features they’d like to see.

Feedback survey - experience

The bad parts

What our testers were missing the most was a full-blown IDE and TypeScript support. Both of these are coming in Beta but only JS was supported at the time. Plus, there were some installation problems with Windows (which is not fully supported yet — best to use it through WSL).

Feedback survey - the bad parts

We were already aware that TypeScript support is an important feature, but didn’t have an exact feeling of how much - the feedback was really helpful and helped us prioritise our Beta backlog.

The good parts

Testers’ favourite part was the batteries-included experience, particularly the auth model.

Feedback survey - the good parts

Post-mortem: what didn’t go well​

No threshold for feedback quality​

Feedback quality

We didn’t put any kind of restrictions on the feedback form, e.g. minimal length of the feedback. That resulted in ~15%-20% of answers being single words, such as depicted above. I’m not sure if there is an efficient way to avoid this or just a stat to live with.

Using free text form for collecting addresses​

It never crossed our minds before that validating addresses could be such an important part of shipping swag, but turns out it is. It seems that there are a lot of ways to specify an address, some of which are different from what is expected by our post office, resulting in a number of shipments getting returned.

An ideal solution would be to use a specialized “address” field in a survey that would auto-validate it, but turns out Typeform (which we used) doesn’t have that feature implemented yet, although it’s been highly requested.

Shipment returned

Shipment returned email

The non-obvious benefit of Alpha Testing Program​

What went well is that we got a lot of high-quality feedback that steered and fortified our plan for the upcoming Beta release.

The other big benefit is that we finally solved the “looks cool but i’ll try it out later maybe” problem. Overall, our usage went well up during the program, but even after it ended, the baseline increased significantly. This was the second-order effect we didn’t foresee.

Our understanding is that once people finally gave it a try, a portion of them felt the value first-hand and decided to keep using it for other projects as well.

Alpha testing program - usage spike

Summary & going forward: Beta​

The overall conclusion from our Alpha Testing Program is it was a worthy effort which got us valuable feedback and positively affected the overall usage. Moving forward we’ll try to focus on ensuring more quality feedback and prioritising 1-to-1 communication to make sure we fully understand what bothers Wasp users and what we can improve. It also might be helpful to do testing in smaller batches so we are not overwhelmed with responses and can focus on the individual testers - that’s something we might try out in Beta.

As mentioned, the next stop is Beta! It comes out on the 27th of November - sign up here to get notified.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Alpha Testing Program: post-mortem

· 7 min read
Matija Sosic

We are working on a new web framework that integrates with React & Node.js, and also happens to be a language. As you can probably imagine, it’s not easy to get people to use a new piece of technology, especially while still in Alpha. On the other hand, without users and their feedback, it’s impossible to know what to build.

That is why we ran Alpha Testing Program for Wasp - here is what we learned and what went both well and wrong along the way.

twitter DM - shared atp in swag groups

“Of course I know about Wasp! I just haven’t come around to trying it out yet.”​

Although we hit the front page of HN several times and are about to reach 2,000 stars on GitHub, there is still a big difference between a person starring a repo and actually sitting down and building something with it.

Talking to people, we realised a lot of them had heard of Wasp, thought it was a neat idea, but hadn’t tried it out. These were the main reasons:

  • having to find 30 mins to go through our Build a Todo App tutorial - “I'm busy now, but I’ll do it next week.”
  • building a bare-bones todo app is not that exciting
  • not having an idea what else to build
  • “the product is still in alpha, so I will bookmark it for later”

These are all obvious and understandable reasons. I must admit, I’m much the same — maybe even worse — when it comes to trying out something new/unproven. It just isn’t a priority, and without a push that will help me overcome all these objections, I usually don’t have an incentive to go through with it.

Having realised all that, we understood we needed to give people a reason to try Wasp out now, because that’s when we needed the feedback, not next week.

Welcome to Wasp Alpha Testing Program!​

The team
I was having a bit too much fun here, but Portal fans will understand.

We quickly put together an admissions page for alpha testers in Notion (you can see it here) and started sharing it around. To counter the hurdles we mentioned above, we time-boxed the program (”this is happening now and you have 48 hours to finish once you start”) and promised a t-shirt to everyone that goes through the tutorial and fills out the feedback form.

Apply to ATP - CTA
CTA from the admissions page

Soon, the first applications started trickling in! For each new applicant, we’d follow up with the instructions on how to successfully go through the Alpha Testing Program:

  • fill out intro form (years of experience, preferred stack, etc)
  • go through our “build a Todo app” tutorial
  • fill out the feedback form - what was good, what was bad etc.

Timeboxing
People were really respectful of this deadline and would politely ask to extend it in case they couldn’t make it.

But, soon after I got the following message on Twitter:

twitter DM - shared atp in swag groups

We got really scared that we would get a ton of folks putting in minimal effort while trying Wasp out just to get the free swag, leaving us empty-handed and having learned nothing! On the other hand, we didn’t have much choice since we didn’t define the “minimum required quality” of feedback in advance.

Luckily, it wasn’t the problem in the end, even the opposite -- we did get a surge of applications, but only a portion of them finished the program and the ones that did left really high-quality feedback!

How it went - test profile & feedback​

Tester profile​

We received 210 applications and 53 out of those completed the program — 25% completion rate.

We also surveyed applicants about their preferred stack, years of programming experience, etc:

Intro survey - tester profile
Yep, we like puns.

The feedback​

The feedback form evaluated testers’ overall experience with Wasp. We asked them what they found to be the best and worst parts of working with Wasp, as well as about the next features they’d like to see.

Feedback survey - experience

The bad parts

What our testers were missing the most was a full-blown IDE and TypeScript support. Both of these are coming in Beta but only JS was supported at the time. Plus, there were some installation problems with Windows (which is not fully supported yet — best to use it through WSL).

Feedback survey - the bad parts

We were already aware that TypeScript support is an important feature, but didn’t have an exact feeling of how much - the feedback was really helpful and helped us prioritise our Beta backlog.

The good parts

Testers’ favourite part was the batteries-included experience, particularly the auth model.

Feedback survey - the good parts

Post-mortem: what didn’t go well​

No threshold for feedback quality​

Feedback quality

We didn’t put any kind of restrictions on the feedback form, e.g. minimal length of the feedback. That resulted in ~15%-20% of answers being single words, such as depicted above. I’m not sure if there is an efficient way to avoid this or just a stat to live with.

Using free text form for collecting addresses​

It never crossed our minds before that validating addresses could be such an important part of shipping swag, but turns out it is. It seems that there are a lot of ways to specify an address, some of which are different from what is expected by our post office, resulting in a number of shipments getting returned.

An ideal solution would be to use a specialized “address” field in a survey that would auto-validate it, but turns out Typeform (which we used) doesn’t have that feature implemented yet, although it’s been highly requested.

Shipment returned

Shipment returned email

The non-obvious benefit of Alpha Testing Program​

What went well is that we got a lot of high-quality feedback that steered and fortified our plan for the upcoming Beta release.

The other big benefit is that we finally solved the “looks cool but i’ll try it out later maybe” problem. Overall, our usage went well up during the program, but even after it ended, the baseline increased significantly. This was the second-order effect we didn’t foresee.

Our understanding is that once people finally gave it a try, a portion of them felt the value first-hand and decided to keep using it for other projects as well.

Alpha testing program - usage spike

Summary & going forward: Beta​

The overall conclusion from our Alpha Testing Program is it was a worthy effort which got us valuable feedback and positively affected the overall usage. Moving forward we’ll try to focus on ensuring more quality feedback and prioritising 1-to-1 communication to make sure we fully understand what bothers Wasp users and what we can improve. It also might be helpful to do testing in smaller batches so we are not overwhelmed with responses and can focus on the individual testers - that’s something we might try out in Beta.

As mentioned, the next stop is Beta! It comes out on the 27th of November - sign up here to get notified.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/11/16/tailwind-feature-announcement.html b/blog/2022/11/16/tailwind-feature-announcement.html index 487545e91d..825911094f 100644 --- a/blog/2022/11/16/tailwind-feature-announcement.html +++ b/blog/2022/11/16/tailwind-feature-announcement.html @@ -19,13 +19,13 @@ - - + + -
-

Feature Announcement - Tailwind CSS support

· 3 min read
Shayne Czyzewski

Full stack devs

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

There are backend devs who can do some frontend, and frontend devs who can do some backend. But the mythical full stack dev is exceedingly rare (or more likely, a lie). Even as someone who falls into the meme category above, we all still need to make websites that look noice. This is a place where CSS frameworks can help.

But which one should you use? According to our extensive research, a statistically-questionable-but-you’re-still-significant-to-us 11 people on Twitter wanted us to add better support for Tailwind. Which was lucky for us, since we already added it before asking them. 😅

Twitter voting

Ok, it wasn’t a huge stretch for us to do so preemptively. Tailwind is one of the most heavily used CSS frameworks out there today and seems to keep growing in popularity. So how do you integrate it into your Wasp apps? Like many things in Wasp, it’s really easy- just drop in two config files into the root of your project and you can then start using it! Here are the defaults:

./tailwind.config.cjs
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}
./postcss.config.cjs
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

When these two files are present, Wasp will make sure all the required NPM dependencies get added, that PostCSS plays nicely with Tailwind directives in CSS files, and that your JavaScript files are properly processed so you can use all the CSS selectors you want (provided you are properly equipped :D).

Best monitor

With that in place, you can add the Tailwind directives to your CSS files like so:

./src/client/Main.css
@tailwind base;
@tailwind components;
@tailwind utilities;

/* rest of content below */

And then start using Tailwind classes in your components:

<h1 className="text-3xl font-bold underline">
  Hello world!
</h1>

As usual, Wasp will still automatically reload your code and refresh the browser on any changes. 🥳

Lastly, here is a small example that shows how to add a few Tailwind plugins for the adventurous (wasp file and Tailwind config), and here are the docs for more details. We can’t wait to see what you make!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Feature Announcement - Tailwind CSS support

· 3 min read
Shayne Czyzewski

Full stack devs

Wasp is a configuration language (DSL) for building full-stack web apps with less code and best practices that works alongside React and Node.js. We are on a mission to streamline web app development while empowering developers to continue using the power of code and their favorite tools. We are backed by Y Combinator and engineers from Airbnb, Facebook, and Lyft.

We are in Beta (try it out)! → Join our community → Work with us

There are backend devs who can do some frontend, and frontend devs who can do some backend. But the mythical full stack dev is exceedingly rare (or more likely, a lie). Even as someone who falls into the meme category above, we all still need to make websites that look noice. This is a place where CSS frameworks can help.

But which one should you use? According to our extensive research, a statistically-questionable-but-you’re-still-significant-to-us 11 people on Twitter wanted us to add better support for Tailwind. Which was lucky for us, since we already added it before asking them. 😅

Twitter voting

Ok, it wasn’t a huge stretch for us to do so preemptively. Tailwind is one of the most heavily used CSS frameworks out there today and seems to keep growing in popularity. So how do you integrate it into your Wasp apps? Like many things in Wasp, it’s really easy- just drop in two config files into the root of your project and you can then start using it! Here are the defaults:

./tailwind.config.cjs
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}
./postcss.config.cjs
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

When these two files are present, Wasp will make sure all the required NPM dependencies get added, that PostCSS plays nicely with Tailwind directives in CSS files, and that your JavaScript files are properly processed so you can use all the CSS selectors you want (provided you are properly equipped :D).

Best monitor

With that in place, you can add the Tailwind directives to your CSS files like so:

./src/client/Main.css
@tailwind base;
@tailwind components;
@tailwind utilities;

/* rest of content below */

And then start using Tailwind classes in your components:

<h1 className="text-3xl font-bold underline">
  Hello world!
</h1>

As usual, Wasp will still automatically reload your code and refresh the browser on any changes. 🥳

Lastly, here is a small example that shows how to add a few Tailwind plugins for the adventurous (wasp file and Tailwind config), and here are the docs for more details. We can’t wait to see what you make!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/11/17/hacktoberfest-wrap-up.html b/blog/2022/11/17/hacktoberfest-wrap-up.html index 2da6bd09b5..ec55b6760c 100644 --- a/blog/2022/11/17/hacktoberfest-wrap-up.html +++ b/blog/2022/11/17/hacktoberfest-wrap-up.html @@ -19,15 +19,15 @@ - - + + -
-

How Wasp reached all-time high PR count during Hacktoberfest: tips for OSS maintainers

· 6 min read

2078 lines of code across 24 PRs were changed in Wasp repo during HacktoberFest 2022 - the most prominent online event for promoting and celebrating OSS culture. October has been a blast, to say the least, and the most active month in the repo's history.

This is the story of our journey along with the tips on leveraging Hacktoberfest to get your repo buzzing! 🐝🐝

How it went: the stats​

Let's take a quick look at the charts below (data obtained from OSS Insight platform) 👇

PR history
24 contributor PRs in Oct, an all-time high!

Lines of code changes
On the other hand, number of changed LoC isn't that huge

While the number of PRs is at an all-time high, the number of updated lines of code is fewer than usual. If we take a look at the distribution of PR sizes in the first chart, we can see that "xs" and "s" PRs are in the majority (20 out of 24).

This brings us to our first conclusion: first-time contributors start with small steps! The main benefit here is getting potential contributors interested and familiar with the project, rather than expecting them to jump in and +

+

How Wasp reached all-time high PR count during Hacktoberfest: tips for OSS maintainers

· 6 min read

2078 lines of code across 24 PRs were changed in Wasp repo during HacktoberFest 2022 - the most prominent online event for promoting and celebrating OSS culture. October has been a blast, to say the least, and the most active month in the repo's history.

This is the story of our journey along with the tips on leveraging Hacktoberfest to get your repo buzzing! 🐝🐝

How it went: the stats​

Let's take a quick look at the charts below (data obtained from OSS Insight platform) 👇

PR history
24 contributor PRs in Oct, an all-time high!

Lines of code changes
On the other hand, number of changed LoC isn't that huge

While the number of PRs is at an all-time high, the number of updated lines of code is fewer than usual. If we take a look at the distribution of PR sizes in the first chart, we can see that "xs" and "s" PRs are in the majority (20 out of 24).

This brings us to our first conclusion: first-time contributors start with small steps! The main benefit here is getting potential contributors interested and familiar with the project, rather than expecting them to jump in and immediately start implementing the next major feature. Efforts like that require investing time to understand and digest codebase architecture, design decisions and the development process.

On the other hand, being able to implement and merge any feature, no matter the size, from beginning to the end, and to get your name on the list of contributors of your favourite project is an amazing feeling! That will make your contributors feel like superheroes and motivate them to keep taking on larger and larger chunks, and maybe eventually even join the core team!

Thus, the second conclusion would be: don’t underestimate the significance of small PRs! It's not about reducing your backlog, but rather encouraging developers to get engaged with your project in a friendly way.

tip

To make it easier for your new contributors, you can prepare in advance good issues to get started with - e.g. smaller bugs, docs improvements, fun but isolated problems, etc.

We added good-first-issue label to such issues in Wasp repo, and even added extra context such as no-haskell, webdev, example, docs.

With your repo being set, the next question is "How do I get people to pick my project to work on"? Relying solely on putting "Hacktoberfest" topic on your GitHub repo won't do the trick, not with thousands of other repos doing the same.

If you want to get noticed, you need to do marketing. A lot of it. The name of the game here is what you put in is what you get back. Let's talk about this in more detail.

A thin line between genuine interactions and annoying self-promotion​

First and foremost, you'll need to create an entry point with all the necessary information for the participants. We opted for a GitHub issue where we categorized Hacktoberfest issues by type, complexity, etc, but it can be anything - a dedicated landing page, Medium/Dev.to article, or whatever works for you. Once you have that, you can start promoting it.

Hacktoberfest entry point - gh issue
Our entry point for Hacktoberfest

Our marketing strategy consisted of the following:

  1. Tweeting regularly - what's new, interesting issues, ...

  2. Writing meaningful Reddit posts about your achievements

  3. Hanging out in HacktoberFest Discord server, chatting with others and answering their questions

  4. Checking posts with appropriate tags on different blogging websites like Medium, Dev.to, Hashnode, etc. and participating in conversations.

There are plenty of other ways to advertise your project, like joining events or writing articles. Even meme contests. The activities mentioned above worked the best for us. Let’s dive a bit deeper.

Tweets are pretty obvious - as mentioned, you can share updates on how stuff is going. Tag contributors, inform your followers about available issues and mention those who might be a good fit for tackling them.

Reddit is a much more complex beast. You need to avoid clickbait post titles, comply with subreddit rules on self-promotion and try to give meaningful info to the community simultaneously. Take less than you give, and you’re good.

posting on reddit
How posting on Reddit feels

The Discord server marketing was pretty straightforward. There’s even a dedicated channel for self-promotion. In case you're not talkative much, dropping a link to your project is OK, and that’s it. On the other hand, the server is an excellent platform for discussing Hacktoberfest-related issues, approaches, and ideas. The more you chat, the higher your chances of drawing attention to your project.

The most engaging but also time consuming activity was commenting on blog posts of other Hacktoberfest participants. Pretending that you’re interested in the topic only to leave a self-promoting comment will not bring you anywhere - it can only result in your comment being removed. Make sure to provide value: add more information on the topic of the article, address specific points the author may have missed, or mention how you’ve dealt with the related issue in your project.

Be consistent and dedicate time to regularly to check new articles and jump into discussions. Share a link to your repo only if it fits into the flow of the conversation.

Content marketing in a nutshell

Was it worth it?​

Before joining HacktoberFest as maintainers, we weren’t sure it would be worth the time investment. Our skepticism was reinforced by the following:

  1. Mentions of people submitting trivial PRs just to win the award

  2. The fact that we're making a relatively complex project (DSL for developing React + Node.js full-stack web apps with less code) and it might be hard for people to get into it

  3. The compiler is written is Haskell, with templates in JavaScript - again, not the very common project setup

Fortunately, none of this turned out to be a problem! We've got 24 valid PRs, both Haskell and non-Haskell, a ton of valuable feedback, and several dozen new users and community members.

Wrap up​

Don’t expect magic to happen. HacktoberFest is all about smaller changes and getting community introduced to your project. Be ready to promote your repo genuinely and don’t be afraid to take part in the contest. We hope that helps and wish you the best of luck!

Remember, HacktoberFest is all about the celebration of open source. Stick to that principle, and you’ll get the results you could only wish for!

P.S. - Thanks to our contributors!​

Massive shout out to our contributors: @ussgarci, @h4r1337, @d0m96, @EmmanuelCoder, @gautier_difolco, @vaishnav_mk1, @NeoLight1010, @abscubix, @JFarayola, @Shahx95 and everyone else for making it possible. You rock! 🤘

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2022/11/26/erlis-amicus-usecase.html b/blog/2022/11/26/erlis-amicus-usecase.html index 76be96b9f4..6a6e0cbb44 100644 --- a/blog/2022/11/26/erlis-amicus-usecase.html +++ b/blog/2022/11/26/erlis-amicus-usecase.html @@ -19,13 +19,13 @@ - - + + -
-

Amicus: See how Erlis built a SaaS for legal teams with Wasp and got first paying customers!

· 5 min read
Matija Sosic

amicus hero shot

Erlis Kllogjri is an engineer based in San Francisco with broad experience ranging from mechanical engineering and C/C++ microcontroller programming to Python and web app development. In his free time, Erlis enjoys working on side projects, which is also how Amicus started out.

Amicus is a SaaS for legal teams - think about it as "Asana for lawyers", but with features and workflows tailored to the domain of law.

Read on to learn how long it took Erlis to develop the first version of his SaaS with Wasp, how he got his first paying customers, and what features he plans to add next!

Looking for a full-stack “all-in-one” solution, with React & Node.js​

Erlis first learned about Wasp on HackerNews and it immediately caught his attention, particularly the configuration language part. One of the companies he worked at in the past had its own internal DSL in the hardware domain, and he understood how helpful it could be for moving fast and avoiding boilerplate.

Erlis also had previous experience in web development, especially on the front-end side in React and Javascript, so that made Wasp a logical choice.

I was looking at other solutions, but none of them were full-stack and sounded like a lot of work just to stitch everything together and get started. I just wanted to get the job done and didn’t care about picking the stack specifics myself. Wasp was really helpful as it set me up with the best practices and I had everything running in just a few minutes!

— Erlis Kllogjri - Amicus

Building Amicus v1.0 and getting first customers!​

The idea for Amicus came from his brother, who is employed at a law firm - talking about their process and challenges in executing them, Erlis thought it would be an interesting side project, especially given there is a real problem to solve.

Soon, the first version of Amicus was live! It was made in a true lean startup fashion, starting with the essential features and immediately being tested with users.

Amicus's dashboard
Amicus's dashboard, using Material-UI

Erlis used Material-UI as a UI library since it came with one of the example apps built in Wasp (Beta introduced Tailwind support!). Users could track their clients, active legal matters and there was even integrated billing with Stripe! Amicus also extensively used Wasp’s Async Jobs feature to regularly update invoices, send reminder emails and clear out old data from the database.

After a few iterations with the legal team who were Amicus' test user (e.g. adding support for different types of users via roles), they were ready to get onboarded and become paying customers! More than 20 people from a single company are using Amicus daily for their work, making it an amazing source of continuous feedback for further development.

Erlis enjoyed the most how fast he could progress and ship features with Wasp on a weekly basis. Having both front-end, back-end, and database set and fully configured to work together from the beginning, he could focus on developing features rather than spend time figuring out the intricacies of the specific stack.

If it weren't for Wasp, Amicus would probably have never been finished. I estimate it saved me 100+ hours from the start and I'm still amazed that I did all this work as a team-of-one. Being able to quickly change existing features and add the new ones is the biggest advantage of Wasp for me.

— Erlis Kllogjri - Amicus

Beyond MVP with Wasp​

Although Erlis already has a product running in production, with first paying customers, he wants to see how far he can take it and has a lot of ideas (also requests) for the next features. (Actually, Erlis had a big kanban board with post-its on a wall behind him as we were chatting, dedicated just to Amicus - that was impressive to see!).

Some of the most imminent ones are:

  • uploading and sharing files between lawyers and clients
  • usage logging and analytics
  • transactional emails for notifications

Since under the hood Wasp is generating code in today's mainstream, production-tested technologies such as React, Node.js and PostgreSQL (through Prisma), there aren't any technical limitations to scaling Amicus as it grows and attracts more users.

Also, given that the wasp build CLI command generates a ready Docker image for the back-end (and static files for the front-end), deployment options are unlimited. Since Heroku is shutting down its free plan, we added guides on how to deploy your project for free on Fly.io and Railway (freemium).

I was using Wasp while still in Alpha and was impressed how well everything worked, especially given how much stuff I get. I had just a few minor issues and the team responded super quickly on Discord and helped me resolve it.

— Erlis Kllogjri - Amicus

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Amicus: See how Erlis built a SaaS for legal teams with Wasp and got first paying customers!

· 5 min read
Matija Sosic

amicus hero shot

Erlis Kllogjri is an engineer based in San Francisco with broad experience ranging from mechanical engineering and C/C++ microcontroller programming to Python and web app development. In his free time, Erlis enjoys working on side projects, which is also how Amicus started out.

Amicus is a SaaS for legal teams - think about it as "Asana for lawyers", but with features and workflows tailored to the domain of law.

Read on to learn how long it took Erlis to develop the first version of his SaaS with Wasp, how he got his first paying customers, and what features he plans to add next!

Looking for a full-stack “all-in-one” solution, with React & Node.js​

Erlis first learned about Wasp on HackerNews and it immediately caught his attention, particularly the configuration language part. One of the companies he worked at in the past had its own internal DSL in the hardware domain, and he understood how helpful it could be for moving fast and avoiding boilerplate.

Erlis also had previous experience in web development, especially on the front-end side in React and Javascript, so that made Wasp a logical choice.

I was looking at other solutions, but none of them were full-stack and sounded like a lot of work just to stitch everything together and get started. I just wanted to get the job done and didn’t care about picking the stack specifics myself. Wasp was really helpful as it set me up with the best practices and I had everything running in just a few minutes!

— Erlis Kllogjri - Amicus

Building Amicus v1.0 and getting first customers!​

The idea for Amicus came from his brother, who is employed at a law firm - talking about their process and challenges in executing them, Erlis thought it would be an interesting side project, especially given there is a real problem to solve.

Soon, the first version of Amicus was live! It was made in a true lean startup fashion, starting with the essential features and immediately being tested with users.

Amicus's dashboard
Amicus's dashboard, using Material-UI

Erlis used Material-UI as a UI library since it came with one of the example apps built in Wasp (Beta introduced Tailwind support!). Users could track their clients, active legal matters and there was even integrated billing with Stripe! Amicus also extensively used Wasp’s Async Jobs feature to regularly update invoices, send reminder emails and clear out old data from the database.

After a few iterations with the legal team who were Amicus' test user (e.g. adding support for different types of users via roles), they were ready to get onboarded and become paying customers! More than 20 people from a single company are using Amicus daily for their work, making it an amazing source of continuous feedback for further development.

Erlis enjoyed the most how fast he could progress and ship features with Wasp on a weekly basis. Having both front-end, back-end, and database set and fully configured to work together from the beginning, he could focus on developing features rather than spend time figuring out the intricacies of the specific stack.

If it weren't for Wasp, Amicus would probably have never been finished. I estimate it saved me 100+ hours from the start and I'm still amazed that I did all this work as a team-of-one. Being able to quickly change existing features and add the new ones is the biggest advantage of Wasp for me.

— Erlis Kllogjri - Amicus

Beyond MVP with Wasp​

Although Erlis already has a product running in production, with first paying customers, he wants to see how far he can take it and has a lot of ideas (also requests) for the next features. (Actually, Erlis had a big kanban board with post-its on a wall behind him as we were chatting, dedicated just to Amicus - that was impressive to see!).

Some of the most imminent ones are:

  • uploading and sharing files between lawyers and clients
  • usage logging and analytics
  • transactional emails for notifications

Since under the hood Wasp is generating code in today's mainstream, production-tested technologies such as React, Node.js and PostgreSQL (through Prisma), there aren't any technical limitations to scaling Amicus as it grows and attracts more users.

Also, given that the wasp build CLI command generates a ready Docker image for the back-end (and static files for the front-end), deployment options are unlimited. Since Heroku is shutting down its free plan, we added guides on how to deploy your project for free on Fly.io and Railway (freemium).

I was using Wasp while still in Alpha and was impressed how well everything worked, especially given how much stuff I get. I had just a few minor issues and the team responded super quickly on Discord and helped me resolve it.

— Erlis Kllogjri - Amicus

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/11/26/michael-curry-usecase.html b/blog/2022/11/26/michael-curry-usecase.html index eae6939241..debb07b72a 100644 --- a/blog/2022/11/26/michael-curry-usecase.html +++ b/blog/2022/11/26/michael-curry-usecase.html @@ -19,13 +19,13 @@ - - + + -
-

How Michael Curry chose Wasp to build Grabbit: an internal tool for managing dev resources at StudentBeans

· 5 min read
Matija Sosic

grabbit hero shot

Michael Curry is a senior front-end engineer at Improbable, a metaverse and simulation company based in London. In his free time he enjoys learning about compilers.

In his previous position at StudentBeans, he experienced the problem of multiple engineering teams competing for the same dev environment (e.g. testing, staging, …). Then he discovered Wasp and decided to do something about it!

Read on to learn why Michael chose Wasp to build and deploy an internal tool for managing development environments at StudentBeans.

The problem: the battle for the dev environment​

StudentBeans has a microservices-based architecture with multiple environments - test, staging, production, …. The team practices CI/CD and deploys multiple times a day. With such a rapid development speed, it would relatively often happen that multiple engineering teams attempt to claim the same dev environment at the same time.

There wasn't an easy way for teams to synchronize on who is using which environment and it would eventually lead to unexpected changes, confusion, and prolonged development times.

The solution: Grabbit - claim and release dev environments as-you-go​

After the incident described above repeated for the n-th time, the team got together for a postmortem. They decided their new development process should look like this:

  • merge your changes
  • claim the environment you want to deploy to (e.g. testing, staging, …)
  • deploy your changes
  • test your changes
  • release the environment once you are done with it so others are able to claim it

The other requirements were to build the solution in-house to save money and also not to spend more than a few hours on it as they still needed to deliver some important features for the ongoing sprint.

The power of rapid prototyping with Wasp​

Michael learned about Wasp during its first HackerNews launch and it immediately caught his eye. Being a programming language enthusiast himself, he immediately understood the value of a DSL approach and how it could drastically simplify the development process, while at the same time not preventing him from using his preferred tech stack (React, Node.js) when needed.

Also, although Michael had full-stack experience, his primary strength at the time was on the front-end side. Wasp looked like a great way of not having to deal with the tedious back-end setup and wiring (setting up the database, figuring out API, …) and being able to focus on the UX.

When I first learned about Wasp on HN I was really excited about its DSL approach. It was amazing how fast I could get things running with Wasp - I had the first version within an hour! The language is also fairly simple and straightforward and plays well with React & Node.js + it removes a ton of boilerplate.

— Michael Curry - Grabbit

Out-of-the-box deployment​

Once Michael was satisfied with the first version of Grabbit, and confirmed with the team it fits their desired process, the only thing left to do was to deploy it! It is well known this step can get really complicated, especially if you're not yet well-versed in the sea of config options that usually come with it.

Wasp CLI comes with a wasp build command that does all the heavy lifting for you - it creates a directory with static front-end files that you can easily deploy to e.g. Netlify, and on the other hand, a Docker image for the back-end. Since Heroku is ending its free plan, our recommendation is to deploy to Fly.io, for which the detailed guide is provided. You can find the detailed deployment instructions here.

In Michael's case, he deployed Grabbit behind the VPN since it was an internal tool, and this process was made easy by having a ready-to-go Dockerfile.

From MVP to a full-fledged SaaS without a rewrite​

The presented functionality of Grabbit above is quite simple (create a resource → claim it → release it), and it could have easily been implemented in some no-code tool or, if we really wanted to go simple, with a Trello board. So why use Wasp at all?

One reason is that developers know and prefer their tools and trust code over the no-code solutions, especially when requirements are still evolving and it is not evident they won't get "stuck" in some closed system. Michael had similar thinking - as he identified this problem at his own company, he realized others must be facing the same issue as well. That is why his plan was to keep improving Grabbit and eventually offer it as a standalone SaaS.

This is where Wasp comes in - he could develop and deploy an initial version of Grabbit in a matter of hours, but still end up with a platform that he can extend indefinitely through the power of code with his stack of choice, React & Node.js, while also using the npm packages he is using everyday at work.

Once he starts adding more advanced features, such as multi-user support with authentication, email notifications, and integration with CI/CD, no-code tools won't cut it any more. This way he saved himself and the company from throwing an MVP away and starting everything from scratch (having to learn the new technology and figure out how to set it all up) as the product evolves.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

How Michael Curry chose Wasp to build Grabbit: an internal tool for managing dev resources at StudentBeans

· 5 min read
Matija Sosic

grabbit hero shot

Michael Curry is a senior front-end engineer at Improbable, a metaverse and simulation company based in London. In his free time he enjoys learning about compilers.

In his previous position at StudentBeans, he experienced the problem of multiple engineering teams competing for the same dev environment (e.g. testing, staging, …). Then he discovered Wasp and decided to do something about it!

Read on to learn why Michael chose Wasp to build and deploy an internal tool for managing development environments at StudentBeans.

The problem: the battle for the dev environment​

StudentBeans has a microservices-based architecture with multiple environments - test, staging, production, …. The team practices CI/CD and deploys multiple times a day. With such a rapid development speed, it would relatively often happen that multiple engineering teams attempt to claim the same dev environment at the same time.

There wasn't an easy way for teams to synchronize on who is using which environment and it would eventually lead to unexpected changes, confusion, and prolonged development times.

The solution: Grabbit - claim and release dev environments as-you-go​

After the incident described above repeated for the n-th time, the team got together for a postmortem. They decided their new development process should look like this:

  • merge your changes
  • claim the environment you want to deploy to (e.g. testing, staging, …)
  • deploy your changes
  • test your changes
  • release the environment once you are done with it so others are able to claim it

The other requirements were to build the solution in-house to save money and also not to spend more than a few hours on it as they still needed to deliver some important features for the ongoing sprint.

The power of rapid prototyping with Wasp​

Michael learned about Wasp during its first HackerNews launch and it immediately caught his eye. Being a programming language enthusiast himself, he immediately understood the value of a DSL approach and how it could drastically simplify the development process, while at the same time not preventing him from using his preferred tech stack (React, Node.js) when needed.

Also, although Michael had full-stack experience, his primary strength at the time was on the front-end side. Wasp looked like a great way of not having to deal with the tedious back-end setup and wiring (setting up the database, figuring out API, …) and being able to focus on the UX.

When I first learned about Wasp on HN I was really excited about its DSL approach. It was amazing how fast I could get things running with Wasp - I had the first version within an hour! The language is also fairly simple and straightforward and plays well with React & Node.js + it removes a ton of boilerplate.

— Michael Curry - Grabbit

Out-of-the-box deployment​

Once Michael was satisfied with the first version of Grabbit, and confirmed with the team it fits their desired process, the only thing left to do was to deploy it! It is well known this step can get really complicated, especially if you're not yet well-versed in the sea of config options that usually come with it.

Wasp CLI comes with a wasp build command that does all the heavy lifting for you - it creates a directory with static front-end files that you can easily deploy to e.g. Netlify, and on the other hand, a Docker image for the back-end. Since Heroku is ending its free plan, our recommendation is to deploy to Fly.io, for which the detailed guide is provided. You can find the detailed deployment instructions here.

In Michael's case, he deployed Grabbit behind the VPN since it was an internal tool, and this process was made easy by having a ready-to-go Dockerfile.

From MVP to a full-fledged SaaS without a rewrite​

The presented functionality of Grabbit above is quite simple (create a resource → claim it → release it), and it could have easily been implemented in some no-code tool or, if we really wanted to go simple, with a Trello board. So why use Wasp at all?

One reason is that developers know and prefer their tools and trust code over the no-code solutions, especially when requirements are still evolving and it is not evident they won't get "stuck" in some closed system. Michael had similar thinking - as he identified this problem at his own company, he realized others must be facing the same issue as well. That is why his plan was to keep improving Grabbit and eventually offer it as a standalone SaaS.

This is where Wasp comes in - he could develop and deploy an initial version of Grabbit in a matter of hours, but still end up with a platform that he can extend indefinitely through the power of code with his stack of choice, React & Node.js, while also using the npm packages he is using everyday at work.

Once he starts adding more advanced features, such as multi-user support with authentication, email notifications, and integration with CI/CD, no-code tools won't cut it any more. This way he saved himself and the company from throwing an MVP away and starting everything from scratch (having to learn the new technology and figure out how to set it all up) as the product evolves.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/11/26/wasp-beta-launch-week.html b/blog/2022/11/26/wasp-beta-launch-week.html index 312c51cad3..2a7416f029 100644 --- a/blog/2022/11/26/wasp-beta-launch-week.html +++ b/blog/2022/11/26/wasp-beta-launch-week.html @@ -19,13 +19,13 @@ - - + + -
-

Wasp Beta Launch Week announcement

· 5 min read
Matija Sosic

It’s almost here! After almost two years since our Alpha release, countless apps developed, React and Node versions upgraded, and PRs merged we’re only a day away from Beta!

Beta is coming

We’re going to follow a launch week format, which means our Beta launch will last for the whole week! Starting with the Product Hunt launch this Sunday (we’ll let you know once we’re live, so sharpen your upvoting fingers!) we’ll highlight a new feature every day.

I’ll try not to spoil too much in advance but we’re really excited about this - here follows a quick overview of what it’s gonna look like:

Sunday, Nov 27 - Product Hunt launch event 🚀 + let’s get this party started: Auth 🎉​

Besides defending our Product Hunt title (we won #1 Product of the Day last time), this time we’ll also have an online party for all of us to celebrate together!

It will be held on our Discord at 9:00 am EST / 15:00 CET - sign up here and make sure to mark yourself as “Interested”!

Join us to meet the team, attend a relaxed AMA session to learn everything about Wasp, from how it started to development challenges (having fun with Haskell, web dev and compilers) and ideas and plans for the future.

Beta launch party instructions

The first feature to announce will be authentication in Wasp! It’s easier and cooler than ever, supports 3rd party providers (hint: starts with “G”), and works smoother than a jar of peanut butter (not the crunchy one of course)!

Monday, Nov 28 - TypeScript support!​

TypeScript is here!

When we asked you what was missing in Wasp during our Alpha Testing Program, you were pretty clear:

TypeScript is wanted!

We heard you (honestly we were missing it too) and now it’s here! You can write your code in TypeScript and enjoy all the goodies that types bring. Some things already work really well and there are a few for which we still have ideas on how to make them better, but more on that on Tuesday!

Wednesday, Nov 29 - Tailwind support! 🐈 💨​

Tailwind Nic Cage

It’s beautiful! Another highly anticipated featured that also comes with Beta - support for Tailwind CSS framework! Since it has an additional build step it didn’t work out-of-the-box with Alpha, but now it works like a breeze (see what I did here?)!

Honestly, having used it for designing our new Beta landing page I can really see why it gained so much popularity. So long, making up names for classes, “containers”, and “wrappers”!

Thursday, Nov 30 - Optimistic updates!​

Without optimistic updates
Stop glitching, dang it!

You know that feeling when you move your Trello card “Try Wasp Beta” from “Todo” column to “Done” column and everything works super smoothly without any glitches? That’s because of optimistic updates! You may not need it often but if you needed and it wasn’t possible you’d feel really sad.

Well, that’s why Alpha is called Alpha and Beta is called Beta 😅. Long story short, now it’s possible to do it in Wasp and it’s also super easy and clean! We're actually very optimistic you’ll feel really good about implementing optimistic updates for your app in Wasp.

Friday, Dec 1 - Improved IDE support, tooling and Wasp LSP!​

VS Code support for Wasp LSP

If you like types in TypeScript (and in general), then you will also enjoy Wasp! Our DSL is also a typed language which means it can report errors in compile time, e.g. in case you haven’t configured your route correctly. And now all that happens directly in your editor!

Beta brings LSP, Language Server for Wasp that works with VS Code (support for other editors coming soon! I’m VIM user myself so take a guess :D). That means improved syntax highlighting, code autocompletion and live error reporting - everything you’d expect from a language!

Wasp Language Server in action
Wasp LSP in action!

Saturday, Dec 2 - Grande Finale + #1 Wasp Hackathon!(Waspathon🐝 ?)​

First Wasp hackathon

I don’t want to reveal too much in advance, but yep there will be a hackathon, yep there will be cool rewards (at least we think so) and yep it will be awesome! We’ll officially announce it as we end the launch week, and equipped with all the new features Beta brought we’ll switch into the hacking mode!

It’s our first hackathon and we can’t wait to tell you more about it (ok, I admit, we’re still working on it) and see what you beeld with Wasp!

Recap​

  • We are launching Beta this Sunday, Nov 27, on Product Hunt at 1am PST / 4am EST / 10am CET - make sure to upvote and comment (anything counts, even “go guys!”) when you can
  • Beta brings a ton of new exciting features - we’ll highlight one each day of the following week
  • On Saturday, Dec 2, we’ll announce a hackathon - our first ever!

That’s it, Waspeteers - keep buzzing as always and see you soon on the other side! 🐝  🅱️

Matija, Martin & the Wasp team

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Wasp Beta Launch Week announcement

· 5 min read
Matija Sosic

It’s almost here! After almost two years since our Alpha release, countless apps developed, React and Node versions upgraded, and PRs merged we’re only a day away from Beta!

Beta is coming

We’re going to follow a launch week format, which means our Beta launch will last for the whole week! Starting with the Product Hunt launch this Sunday (we’ll let you know once we’re live, so sharpen your upvoting fingers!) we’ll highlight a new feature every day.

I’ll try not to spoil too much in advance but we’re really excited about this - here follows a quick overview of what it’s gonna look like:

Sunday, Nov 27 - Product Hunt launch event 🚀 + let’s get this party started: Auth 🎉​

Besides defending our Product Hunt title (we won #1 Product of the Day last time), this time we’ll also have an online party for all of us to celebrate together!

It will be held on our Discord at 9:00 am EST / 15:00 CET - sign up here and make sure to mark yourself as “Interested”!

Join us to meet the team, attend a relaxed AMA session to learn everything about Wasp, from how it started to development challenges (having fun with Haskell, web dev and compilers) and ideas and plans for the future.

Beta launch party instructions

The first feature to announce will be authentication in Wasp! It’s easier and cooler than ever, supports 3rd party providers (hint: starts with “G”), and works smoother than a jar of peanut butter (not the crunchy one of course)!

Monday, Nov 28 - TypeScript support!​

TypeScript is here!

When we asked you what was missing in Wasp during our Alpha Testing Program, you were pretty clear:

TypeScript is wanted!

We heard you (honestly we were missing it too) and now it’s here! You can write your code in TypeScript and enjoy all the goodies that types bring. Some things already work really well and there are a few for which we still have ideas on how to make them better, but more on that on Tuesday!

Wednesday, Nov 29 - Tailwind support! 🐈 💨​

Tailwind Nic Cage

It’s beautiful! Another highly anticipated featured that also comes with Beta - support for Tailwind CSS framework! Since it has an additional build step it didn’t work out-of-the-box with Alpha, but now it works like a breeze (see what I did here?)!

Honestly, having used it for designing our new Beta landing page I can really see why it gained so much popularity. So long, making up names for classes, “containers”, and “wrappers”!

Thursday, Nov 30 - Optimistic updates!​

Without optimistic updates
Stop glitching, dang it!

You know that feeling when you move your Trello card “Try Wasp Beta” from “Todo” column to “Done” column and everything works super smoothly without any glitches? That’s because of optimistic updates! You may not need it often but if you needed and it wasn’t possible you’d feel really sad.

Well, that’s why Alpha is called Alpha and Beta is called Beta 😅. Long story short, now it’s possible to do it in Wasp and it’s also super easy and clean! We're actually very optimistic you’ll feel really good about implementing optimistic updates for your app in Wasp.

Friday, Dec 1 - Improved IDE support, tooling and Wasp LSP!​

VS Code support for Wasp LSP

If you like types in TypeScript (and in general), then you will also enjoy Wasp! Our DSL is also a typed language which means it can report errors in compile time, e.g. in case you haven’t configured your route correctly. And now all that happens directly in your editor!

Beta brings LSP, Language Server for Wasp that works with VS Code (support for other editors coming soon! I’m VIM user myself so take a guess :D). That means improved syntax highlighting, code autocompletion and live error reporting - everything you’d expect from a language!

Wasp Language Server in action
Wasp LSP in action!

Saturday, Dec 2 - Grande Finale + #1 Wasp Hackathon!(Waspathon🐝 ?)​

First Wasp hackathon

I don’t want to reveal too much in advance, but yep there will be a hackathon, yep there will be cool rewards (at least we think so) and yep it will be awesome! We’ll officially announce it as we end the launch week, and equipped with all the new features Beta brought we’ll switch into the hacking mode!

It’s our first hackathon and we can’t wait to tell you more about it (ok, I admit, we’re still working on it) and see what you beeld with Wasp!

Recap​

  • We are launching Beta this Sunday, Nov 27, on Product Hunt at 1am PST / 4am EST / 10am CET - make sure to upvote and comment (anything counts, even “go guys!”) when you can
  • Beta brings a ton of new exciting features - we’ll highlight one each day of the following week
  • On Saturday, Dec 2, we’ll announce a hackathon - our first ever!

That’s it, Waspeteers - keep buzzing as always and see you soon on the other side! 🐝  🅱️

Matija, Martin & the Wasp team

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/11/28/why-we-chose-prisma.html b/blog/2022/11/28/why-we-chose-prisma.html index 1f0c5833c9..64adeb033a 100644 --- a/blog/2022/11/28/why-we-chose-prisma.html +++ b/blog/2022/11/28/why-we-chose-prisma.html @@ -19,13 +19,13 @@ - - + + -
-

Why we chose Prisma as a database layer for Wasp

· 7 min read
Martin Sosic

Beta is coming

Wasp is a full-stack JS web dev framework, covering frontend, backend, and database. When choosing the solution to build our database layer on top, we chose Prisma, even though it was still somehwat new tech at that point, and we believe today we made a great choice -> read on to learn why!

At Wasp, we aim to simplify full-stack web development via a specialized high-level language. This language allows you to describe the main parts of your web app succinctly, avoiding a lot of usual boilerplate and configuration while giving you lots of features and ensuring best practices. Wasp is essentially a full-stack web framework implemented as a specialized language that works with React & Node.js!

When we started working on Wasp, we wanted to keep it easy to learn and to the point, so we decided:

  • the Wasp language should only be used at a high level, so you would still use React, NodeJS, HTML, CSS, etc. to implement your custom logic. If a full-stack web app is an orchestra, Wasp is the conductor.
  • the Wasp language should be declarative and simple, very similar to JSON, but “smarter” in the sense it understands web app concepts and makes sure your app follows them.

With that in mind, we focused on identifying high-level web app concepts that are worth capturing in the Wasp language. We identified the following parts of a web app:

  • General app info (title, head, favicon, …)
  • Pages and Routes
  • Data Models (aka Entities), e.g. User, Task, Organization, Article, … .
  • Operations (communication between client and server; CRUD on data models, 3rd party APIs, …)
  • Deployment

Entities​

Of all of those, Entities are in the middle of everything, present through the whole codebase, and are central to all the other parts of the web app: client, server, and database. They were, however, also the most daunting part to implement!

When we started, we imagined an Entity would look something like this in Wasp:

entity User {
  id: Id,
  username: String @unique,
  email: String @unique
  groups: [Group]
}

While adding this initial syntax to our language was feasible, there were also much bigger tasks to tackle in order to make this a proper solution:

  • expand syntax to be flexible enough for real-life use cases
  • support migrations (data and schema)
  • generate code that users can call from JS/TS to query and update entities in the DB
  • and probably a lot of other things that we hadn’t even thought of yet!

Mongoose, Sequelize, … or Prisma?​

We already decided that we would pick an ORM(ish) solution for JS/TS which we would build the rest of the features on top of. We started evaluating different ones: Mongoose, Sequelize, TypeORM, … .

But then we looked at Prisma, and the winner was clear! Not only was Prisma taking care of everything that we cared about, but it had one additional feature that made it a perfect fit:

model User {
  id          Int     @id @default(autoincrement())
  username    String  @unique
  password    String
}

No, this is not another idea of how the syntax for Entities could look like in Wasp language → this is the Prisma Schema Language (PSL)!!!

Prisma Schema Language (PSL)​

Indeed, Prisma is unique in having a special, declarative language for describing data models (schema), and it was exactly what we needed for Wasp.

So instead of implementing our own syntax for describing Entities, we decided to use Prisma and their PSL to describe Entities (data models) inside the Wasp language.

Today, Entities are described like this in Wasp language:

// ... some Wasp code ...

entity User {=psl
  id          Int     @id @default(autoincrement())
  username    String  @unique
  password    String
psl=} 

// ... some Wasp code ...

So in the middle of Wasp, you just switch to writing PSL (Prisma Schema Language) to describe an entity!

Another great thing is that the PSL is at its core a pretty simple language, so we implemented our own parser for it → that means that Wasp actually understands what you wrote, even though it is PSL, and can fully work with it. So we lost nothing by using PSL instead of our own syntax and instead gained all the features that Prisma brings.

Other Benefits​

Besides PSL, there were plenty of other reasons why we felt Prisma is a great fit for us:

  • It is targeting Javascript / Typescript.
  • It takes care of migrations and has a nice workflow for doing it.
  • It supports different databases: Mongo, PostgreSQL, CockroachDB, …, which is very important for Wasp since our vision is to support different stacks in the future.
  • It has Prisma Studio - UI for inspecting your database, which we also make available to you via Wasp CLI.
  • It keeps improving quickly and is very focused on a nice developer experience, which is also our focus here at Wasp.
  • Community is extremely welcoming and the core team is super helpful - all of our questions and issues were answered super quickly!

Challenges​

While integrating Prisma into Wasp went really smoothly, there were a few hiccups:

  • Getting Prisma CLI to provide interactive output while being called programmatically by Wasp was tricky, and in the end, we had to use a bit of a dirty approach to trick the Prisma CLI into thinking it is called interactively. We opened an issue for this with Prisma, so hopefully, we will be able to remove this once it is resolved: https://github.com/prisma/prisma/issues/7113.
  • In the early days, there were some bugs, however, they were always quickly solved, so updating to the newest Prisma version was often the solution.
  • It took us a bit of fiddling to get Prisma to work with its schema outside of the server’s root directory, but we did get it working in the end!

Most of these were due to us stretching the boundaries of how Prisma was imagined to be used, but in total Prisma proved to be fairly flexible!

Summary​

With its declarative language for describing schema, focus on ergonomics, and JS/TS as the target language, Prisma was really a stroke of luck for us - if not for it, it would have taken much more effort to get the Entities working in Wasp.

When we started using it, Prisma was still somewhat early, and it was certainly the least-mature technology in our stack - but we decided to bet on it because it was just a perfect fit, and it made so much sense. Today, with Prisma being a mature and popular solution, we are more than happy we made that choice!

Future​

Already, Prisma is playing a big role at Wasp, but there is still more that we plan and want to do:

  • support Prisma’s Enum and Type declarations
  • expose more of Prisma’s CLI commands, especially database seeding
  • add support in Wasp for multiple databases (which Prisma already supports)
  • improve IDE support for PSL within the Wasp language

If you are interested in helping with any of these, reach out to us on this issue https://github.com/wasp-lang/wasp/issues/641, or in any case, join us on our Discord server!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Why we chose Prisma as a database layer for Wasp

· 7 min read
Martin Sosic

Beta is coming

Wasp is a full-stack JS web dev framework, covering frontend, backend, and database. When choosing the solution to build our database layer on top, we chose Prisma, even though it was still somehwat new tech at that point, and we believe today we made a great choice -> read on to learn why!

At Wasp, we aim to simplify full-stack web development via a specialized high-level language. This language allows you to describe the main parts of your web app succinctly, avoiding a lot of usual boilerplate and configuration while giving you lots of features and ensuring best practices. Wasp is essentially a full-stack web framework implemented as a specialized language that works with React & Node.js!

When we started working on Wasp, we wanted to keep it easy to learn and to the point, so we decided:

  • the Wasp language should only be used at a high level, so you would still use React, NodeJS, HTML, CSS, etc. to implement your custom logic. If a full-stack web app is an orchestra, Wasp is the conductor.
  • the Wasp language should be declarative and simple, very similar to JSON, but “smarter” in the sense it understands web app concepts and makes sure your app follows them.

With that in mind, we focused on identifying high-level web app concepts that are worth capturing in the Wasp language. We identified the following parts of a web app:

  • General app info (title, head, favicon, …)
  • Pages and Routes
  • Data Models (aka Entities), e.g. User, Task, Organization, Article, … .
  • Operations (communication between client and server; CRUD on data models, 3rd party APIs, …)
  • Deployment

Entities​

Of all of those, Entities are in the middle of everything, present through the whole codebase, and are central to all the other parts of the web app: client, server, and database. They were, however, also the most daunting part to implement!

When we started, we imagined an Entity would look something like this in Wasp:

entity User {
  id: Id,
  username: String @unique,
  email: String @unique
  groups: [Group]
}

While adding this initial syntax to our language was feasible, there were also much bigger tasks to tackle in order to make this a proper solution:

  • expand syntax to be flexible enough for real-life use cases
  • support migrations (data and schema)
  • generate code that users can call from JS/TS to query and update entities in the DB
  • and probably a lot of other things that we hadn’t even thought of yet!

Mongoose, Sequelize, … or Prisma?​

We already decided that we would pick an ORM(ish) solution for JS/TS which we would build the rest of the features on top of. We started evaluating different ones: Mongoose, Sequelize, TypeORM, … .

But then we looked at Prisma, and the winner was clear! Not only was Prisma taking care of everything that we cared about, but it had one additional feature that made it a perfect fit:

model User {
  id          Int     @id @default(autoincrement())
  username    String  @unique
  password    String
}

No, this is not another idea of how the syntax for Entities could look like in Wasp language → this is the Prisma Schema Language (PSL)!!!

Prisma Schema Language (PSL)​

Indeed, Prisma is unique in having a special, declarative language for describing data models (schema), and it was exactly what we needed for Wasp.

So instead of implementing our own syntax for describing Entities, we decided to use Prisma and their PSL to describe Entities (data models) inside the Wasp language.

Today, Entities are described like this in Wasp language:

// ... some Wasp code ...

entity User {=psl
  id          Int     @id @default(autoincrement())
  username    String  @unique
  password    String
psl=} 

// ... some Wasp code ...

So in the middle of Wasp, you just switch to writing PSL (Prisma Schema Language) to describe an entity!

Another great thing is that the PSL is at its core a pretty simple language, so we implemented our own parser for it → that means that Wasp actually understands what you wrote, even though it is PSL, and can fully work with it. So we lost nothing by using PSL instead of our own syntax and instead gained all the features that Prisma brings.

Other Benefits​

Besides PSL, there were plenty of other reasons why we felt Prisma is a great fit for us:

  • It is targeting Javascript / Typescript.
  • It takes care of migrations and has a nice workflow for doing it.
  • It supports different databases: Mongo, PostgreSQL, CockroachDB, …, which is very important for Wasp since our vision is to support different stacks in the future.
  • It has Prisma Studio - UI for inspecting your database, which we also make available to you via Wasp CLI.
  • It keeps improving quickly and is very focused on a nice developer experience, which is also our focus here at Wasp.
  • Community is extremely welcoming and the core team is super helpful - all of our questions and issues were answered super quickly!

Challenges​

While integrating Prisma into Wasp went really smoothly, there were a few hiccups:

  • Getting Prisma CLI to provide interactive output while being called programmatically by Wasp was tricky, and in the end, we had to use a bit of a dirty approach to trick the Prisma CLI into thinking it is called interactively. We opened an issue for this with Prisma, so hopefully, we will be able to remove this once it is resolved: https://github.com/prisma/prisma/issues/7113.
  • In the early days, there were some bugs, however, they were always quickly solved, so updating to the newest Prisma version was often the solution.
  • It took us a bit of fiddling to get Prisma to work with its schema outside of the server’s root directory, but we did get it working in the end!

Most of these were due to us stretching the boundaries of how Prisma was imagined to be used, but in total Prisma proved to be fairly flexible!

Summary​

With its declarative language for describing schema, focus on ergonomics, and JS/TS as the target language, Prisma was really a stroke of luck for us - if not for it, it would have taken much more effort to get the Entities working in Wasp.

When we started using it, Prisma was still somewhat early, and it was certainly the least-mature technology in our stack - but we decided to bet on it because it was just a perfect fit, and it made so much sense. Today, with Prisma being a mature and popular solution, we are more than happy we made that choice!

Future​

Already, Prisma is playing a big role at Wasp, but there is still more that we plan and want to do:

  • support Prisma’s Enum and Type declarations
  • expose more of Prisma’s CLI commands, especially database seeding
  • add support in Wasp for multiple databases (which Prisma already supports)
  • improve IDE support for PSL within the Wasp language

If you are interested in helping with any of these, reach out to us on this issue https://github.com/wasp-lang/wasp/issues/641, or in any case, join us on our Discord server!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/11/29/permissions-in-web-apps.html b/blog/2022/11/29/permissions-in-web-apps.html index 65924b39e7..1f9352b02c 100644 --- a/blog/2022/11/29/permissions-in-web-apps.html +++ b/blog/2022/11/29/permissions-in-web-apps.html @@ -19,12 +19,12 @@ - - + + -
-

Permissions (access control) in web apps

· 19 min read
Martin Sosic

At Wasp, we are working on a config language / DSL for building web apps that integrates with React & Node.js.
+

+

Permissions (access control) in web apps

· 19 min read
Martin Sosic

At Wasp, we are working on a config language / DSL for building web apps that integrates with React & Node.js.
This requires us to deeply understand different parts of what constitutes a web app, in order to be able to model them in our DSL.

Recently our focus was on access control, and I decided to capture the learnings in this blog post, to help others quickly get up to speed on how to do access control in web apps.
So, if you are new to access control in web apps, or have been doing it for some time but want to get a better idea of standard practices, read along!

Quick overview of what this blog post covers:​

  1. Permissions, yay! Wait, what are they though? (quick overview of basic terms)
  2. Where do we check permissions in a web app: frontend vs backend vs db
  3. Common approaches (RBAC, ABAC, …)
  4. OWASP recommendations
  5. Implementing access control in practice
  6. Summary (TLDR)

1. Permissions, yay! Wait, what are they though?​

Unless your web app is mostly about static content or is a form of art, it will likely have a notion of users and user accounts.

Artistic dolphin painting with brush
This dolphin doesn't need users

In such a case, you will need to know which user has permissions to do what -> who can access which resources, and who can execute which operations.

Some common examples of permissions in action:

  1. User can access only their own user account.
  2. If the user is an admin, they can ban other users’ accounts.
  3. User can read other users’ articles, but can't modify them.
  4. The title and description of the article behind the paywall are publicly accessible, but the content is not.
  5. User can send an email invitation to up to 10 future users per day.

Aha, you mean access control! Sorry, authorization! Hmm, authentication?​

There are different terms out there (authentication, authorization, access control, permissions) that are often confused for each other, so let's quickly clarify what each one of them stands for.

Spidermen representing authN, authZ, AC and permissions pointing at each other
They all look the same!

1) Authentication (or as cool kids would say: authN)​

Act of verifying the user's identity.
Answers the question "Who are they?"

A: Knock Knock
@@ -45,7 +45,7 @@ An interesting finding is that even though the sample is pretty small, it is clear that devs prefer RBAC over OWASP-recommended ABAC.
I believe this is due to 2 main reasons: RBAC is simpler + there are more libraries/frameworks out there supporting RBAC than ABAC (again, due to it being simpler).
It does seem that ABAC is picking up recently though, so it would be interesting to repeat this poll in the future and see what changes.

Organic development​

Organic growth of my code (meme)

Often, we add permission checks to our web app one by one, as needed. For example, if we are using NodeJS with ExpressJS for our server and writing middleware that handles HTTP API requests, we will add a bit of logic into that middleware that does some checks to ensure a user can actually perform that action. Or maybe we will embed “checks” into our database queries so that we query only what the user is allowed to access. Often a combination.

What can be dangerous with such an organic approach is the complexity that arises as the codebase grows - if we don’t put enough effort into centralizing and structuring our access control logic, it can become very hard to reason about it and to do consistent updates to it, leading to mistakes and vulnerabilities.

Imagine having to modify the web app so that user can now only read their own articles and articles of their friends, while before they were allowed to read any article. If there is only one place where we can make this update, we will have a nice time, but if there are a bunch of places and we need to hunt those down first and then make sure they are all updated in the same way, we are in for a lot of trouble and lot of space to make mistakes.

Using an existing solution​

Instead of figuring out on our own how to structure the access control code, often it is a better choice to use an existing access control solution! Besides not having to figure and implement everything on your own, another big advantage is that these solutions are battle-tested, which is very important for the code dealing with the security of your web app.

We can roughly divide these solutions into frameworks and (external) providers, where frameworks are embedded into your web app and shipped together with it, while providers are externally hosted and usually paid services.

A couple of popular solutions:

  1. https://casbin.org/ (multiple approaches, multiple languages, provider)
    1. Open source authZ library that has support for many access control models (ACL, RBAC, ABAC, …) and many languages (Go, Java, Node.js, JS, Rust, …). While somewhat complex, it is also powerful and flexible. They also have their Casdoor platform, which is authN and authZ provider.
  2. https://casl.js.org/v5/en/ (ABAC, Javascript)
    1. Open source JS/TS library for ABAC. CASL gives you a nice way to define the ABAC rules in your web / NodeJS code, and then also check them and call them. It has a bunch of integrations with popular solutions like React, Angular, Prisma, Mongoose, … .
  3. https://github.com/CanCanCommunity/cancancan (Ruby on Rails ABAC)
    1. Same like casl.js, but for Ruby on Rails! Casl.js was actually inspired and modeled by cancancan.
  4. https://github.com/varvet/pundit
    1. Popular open-source Ruby library focused around the notion of policies, giving you the freedom to implement your own approach based on that.
  5. https://spring.io/projects/spring-security
    1. Open source authN and authZ framework for Spring (Java).
  6. https://github.com/dfunckt/django-rules
    1. A generic, approachable open source framework for building rule-based systems in Django (Python).
  7. Auth0 (provider)
    1. Auth0 has been around for some time and is probably the most popular authN provider out there. While authN is their main offering (they give you SDKs for authentication + they store user profiles and let you manage them through their SaaS), they also allow you to define authZ to some degree, via RBAC and policies.
  8. https://www.osohq.com/ (provider, DSL)
    1. OSO is an authZ provider, unique in a way that they have a specialized language for authorization (DSL, called Polar) in which you define your authorization rules. They come with support for common approaches (e.g. RBAC, ABAC, ReBAC) but also support custom ones. Then, you can use their open source library embedded in your application, or use their managed cloud offering.
  9. https://warrant.dev/ (Provider)
    1. Relatively new authZ provider, they have a dashboard where you can manage your rules in a central location and then use them from multiple languages via their SDKs, even on the client to perform UI checks. Rules can also be managed programmatically via SDK.
  10. https://authzed.com/ (Provider)
    1. AuthZed brings a specialized SpiceDB permissions database which they use as a centralized place for storing and managing rules. Then, you can use their SDKs to query, store, and validate application permissions.

Summary (TLDR)​

  • Authentication (authN) answers “who are they”, authorization (authZ) answers “are they allowed to”, while access control is the overarching term for the whole process of performing authN and authZ.
  • Doing access control on the frontend is just for show (for improving UX) and you can’t rely on it. Any and all real access control needs to be done on the server (possibly a bit in the db, but normally not needed).
  • While it is ok to start with a simple access control approach at the beginning, you should be ready to switch to a more advanced approach once the complexity grows. The most popular approaches for doing access control are RBAC (role-based) and ABAC (attribute-based). RBAC is easier to get going with, but ABAC is more powerful.
  • You should make sure your access control has as little duplication as possible and is centralized, in order to reduce the chance of introducing bugs.
  • It is usually smart to use existing solutions, like access control frameworks or external providers.

Access control in Wasp​

In Wasp, we don’t yet have special support for access control, although we are planning to add it in the future. As it seems at the moment, we will probably go for ABAC, and we would love to provide a way to define access rules both at the Operations level and at Entity (data model) level. Due to Wasp’s mission to provide a highly integrated full-stack experience, we are excited about the possibilities this offers to provide an access control solution that is integrated tightly with the whole web app, through the whole stack!

You can check out our discussion about this in our “Support for Permissions” RFC.

Thanks to the reviewers​

Karan Kajla (pro advice on RBAC!), Graham Neray (great general advice + pointed out ReBAC), Dennis Walsh (awesome suggestions how to have article read better), Shayne Czyzewski, Matija Sosic, thank you for taking the time to review this article and make it better! Your suggestions, corrections, and ideas were invaluable.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2022/11/29/typescript-feature-announcement.html b/blog/2022/11/29/typescript-feature-announcement.html index d3e4895675..621b24b7aa 100644 --- a/blog/2022/11/29/typescript-feature-announcement.html +++ b/blog/2022/11/29/typescript-feature-announcement.html @@ -19,16 +19,16 @@ - - + + -
-

Feature Announcement - TypeScript Support

· 8 min read
Filip Sodić

Wasp TS support

We are in Beta (try it out)! → Join our community → Work with us

Prologue​

TypeScript doesn't need much introduction at this point, so we'll keep it short! +

+

Feature Announcement - TypeScript Support

· 8 min read
Filip Sodić

Wasp TS support

We are in Beta (try it out)! → Join our community → Work with us

Prologue​

TypeScript doesn't need much introduction at this point, so we'll keep it short! Wasp finally allows you to write your code in TypeScript (i.e., the most popular web technology after JavaScript) on both the front-end and the back-end.

You can now define and use types in any part of your code, enjoying all benefits of the static type checker. At the time of writing, not all parts of Wasp are typed as well as they could be, but we're working on it! Exposing all Wasp functionalities through informative typed interfaces is one of our top priorities.

Without further ado, let's see how we can use TypeScript with Wasp.

Setting up a TypeScript project in Wasp​

Let's start by creating a fresh Wasp project:

wasp new myApp

This will generate a project skeleton in the folder myApp. The project structure is different than before, and there are now several additional generated files that help with IDE and TypeScript support. So let's explain it:

.
├── .gitignore
├── main.wasp             # Your wasp code goes here.
├── src
│   ├── client            # Your client code (JS/CSS/HTML) goes here.
│   │   ├── Main.css
│   │   ├── MainPage.jsx
│   │   ├── react-app-env.d.ts
│   │   ├── tsconfig.json
│   │   └── waspLogo.png
│   ├── server            # Your server code (Node JS) goes here.
│   │   └── tsconfig.json
│   ├── shared            # Your shared (runtime independent) code goes here.
│   │   └── tsconfig.json
│   └── .waspignore
└── .wasproot

At this point, we can choose one of three options:

  1. We write our code exclusively in JavaScript.
  2. We write our code exclusively in TypeScript.
  3. We write some parts of our code in JavaScript, and other parts in TypeScript.

Since the third option is a superset of the first two, that's what Wasp currently supports. In other words, regardless of whether you want your entire codebase in one of these languages or you want to mix it up, there's no extra configuration necessary! Simply use the appropriate extension (.ts and .tsx for TypeScript; .js and .jsx for JavaScript), and your IDE and Wasp will know what to do.

To demonstrate this, let's start Wasp and change MainPage.jsx to MainPage.tsx:

wasp start
mv src/client/MainPage.jsx src/client/MainPage.tsx

That's it! Wasp will notice the change and recompile, and your app will continue to work. The only difference is that you can now write TypeScript in MainPage.tsx and get helpful information from your IDE and the static type checker. Try removing an import and see what happens.

The same applies to any file you may want to include in your project. Specify the language you wish to use via the extension, and Wasp will do the rest!

caution

Even if you use TypeScript and have a server file called someFile.ts, you must still import it as if it had the .js extension (i.e., import foo from 'someFile.js'). Wasp internally uses esnext module resolution, which always requires specifying the extension as .js (i.e., the extension used in the emitted JS file). This applies to all @server imports (and files on the server in general).

Read more about ES modules in TypeScript here. If you're interested in the discussion and the reasoning behind this, read about it in this GitHub issue.

This does not apply to front-end files. Thanks to Webpack, you don't need to write extensions when working with client-side imports.

Moving existing projects to the new structure (and optionally TypeScript)​

If you wish to move an existing project to the new structure, the easiest approach comes down to creating a new project and moving all the files from your old project into appropriate locations. After doing this, you can choose which files you'd like to implement in TypeScript, change the extension and go for it.

To avoid digging too deep, this is all we'll say about migrating. For a more detailed migration guide, check our changelog. It explains everything step-by-step.

TypeScript in action​

Finally, let's demonstrate how TypeScript helps us by using it in a small Todo app. The part of our code in charge of rendering tasks looks something like this:


function MainPage() {
  const { data: tasks } = useQuery(getTasks)

  return (
    <div>
      <h1>Todos</h1>
      <TaskList tasks={tasks} />
    </div>
  )
}

function TaskList({ tasks }) {
  if (!tasks.len) {
    return <div>No tasks</div>
  }

  return (
    <div>
      {tasks.map((task, idx) => <Task {...task} key={idx}/>)}
    </div>
  )
}



function Task({ id, isdone, description }) {
  return (
    <div>
      <label>
        <input
          type='checkbox'
          id={id}
          checked={isdone}
          onChange={
            (event) => updateTask({ id, isDone: event.target.checked })
          }
        />
        <span>{description}</span>
      </label>
    </div>
  )
}

Try to see if you can find any bugs. When you're confident you've got all of them, continue reading.

Let's see what happens when we bring TypeScript into the picture. Remember, we only need to change the extension to tsx. After we do this, The IDE will warn us about missing type definitions, so let's fill these in. While we're at it, we can also tell useQuery what types it's working with by specifying its type arguments.

Here's how our code looks after these changes:

type Task = {
  id: string
  description: string
  isDone: boolean
}

function MainPage() {
  const { data: tasks } = useQuery<Task, Task[]>(getTasks)

  return (
    <div>
      <h1>Todos</h1>
      <TaskList tasks={tasks} />
    </div>
  )
}

function TaskList({ tasks }: { tasks: Task[] }) {
  if (!tasks.len) {
    return <div>No tasks</div>
  }

  return (
    <div>
      {tasks.map((task, idx) => <Task {...task} key={idx}/>)}
    </div>
  )
}



function Task({ id, isdone, description }: Task) {
  return (
    <div>
      <label>
        <input
          type='checkbox'
          id={id}
          checked={isdone}
          onChange={
            (event) => updateTask({ id, isDone: event.target.checked })
          }
        />
        <span>{description}</span>
      </label>
    </div>
  )
}

As soon as we change our code, TypeScript detects three errors:

TypeScript erros
The errors are pretty simple (almost as if we've made them up for this example :)

  1. The first error warns us that tasks might be undefined (e.g., on the first render), which TaskList does not expect
  2. The second error tells us that the property len does not exist on the array tasks. In other words, we misspelled length.
  3. Finally, the third error tells us that the type Task does not contain the field isdone. This is also a typo. The field's name should be isDone.

Thanks to TypeScript, we can quickly fix all three errors, saving us a lot of time we'd probably lose by hunting them down manually or, even worse, during runtime.


type Task = {
  id: string
  description: string
  isDone: boolean
}
function MainPage() {
  const { data: tasks } = useQuery<Task, Task[]>(getTasks)

  return (
    <div>
      <h1>Todos</h1>
      {tasks && <TaskList tasks={tasks} />}
    </div>
  )
}

function TaskList({ tasks }: { tasks: Task[] }) {
  if (!tasks.length) {
    return <div>No tasks</div>
  }

  return (
    <div>
      {tasks.map((task, idx) => <Task {...task} key={idx} />)}
    </div>
  )
}



function Task({ id, isDone, description }: Task) {
  return (
    <div>
      <label>
        <input
          type='checkbox'
          id={id}
          checked={isDone}
          onChange={
            (event) => updateTask({ id, isDone: event.target.checked })
          }
        />
        <span>{description}</span>
      </label>
    </div>
  )
}

And that's it! This is the joy of TypeScript. We've easily fixed all reported errors, and our code should now work correctly (well, at least less incorrectly).

Future work​

You might have noticed that, if we want to use the Task type, we have to write most of its type definition twice - once when defining the Task entity in the .wasp file and then again in our code. While we can define the type in src/shared to avoid writing (almost) the same code on both the server and the client, we'll still have duplication between the code in src/shared and our .wasp file.

The good news is that we know about this, also find it annoying, and are working to fix it as soon as possible! In the near future, Wasp will generate types from entities and allow you to access them using @wasp imports. Other improvements exist, too. For example, Wasp could read your query declarations and provide you with the correct type for the context object in their definitions. Another possible improvement is automatically typing queries on the front-end, and then relying on type inference to correctly type useQuery (instead of users specifying its type arguments explicitly).

In short, there's a long and exciting path ahead of us, full of interesting possibilities. So stick with Wasp and see how far we can make it!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2022/11/29/wasp-beta.html b/blog/2022/11/29/wasp-beta.html index b5cbc43322..b6fe802112 100644 --- a/blog/2022/11/29/wasp-beta.html +++ b/blog/2022/11/29/wasp-beta.html @@ -19,14 +19,14 @@ - - + + -
-

Wasp is in Beta: Auth, TypeScript, Tailwind, LSP

· 3 min read
Matija Sosic

Wasp is a simple configuration language for building full-stack web apps with less code and ensured best practices. It integrates with React, Node.js and Prisma and provides a lot of common features (auth, CRUD, async jobs, ...) out of the box.

Today, we’re moving to Beta.

Since the launch of Wasp Alpha in February 2021, we’ve been fortunate to work with hundreds of early adopters who helped us shape the product and prioritise the features to build. Number of applications have been deployed to production and even the first revenue generating product was built on top of Wasp.

Alpha in numbers​

  • 1,011 projects created
  • 2,012 GitHub stars
  • 45 GitHub contributors
  • 243 issues closed
  • 42,170 lines of code

Here are the the new features that ship with Beta:

🟦 TypeScript support​

Developers can now write all their code in TypeScript both on client and server. We’re also in the process of migrating our codebase and adding new types to Wasp imports every day.

Learn more here →

🔑 Full-stack authentication​

Besides username & password, Wasp now also supports authentication with Google. We offer both UI helpers (forms you can just import) and functions you can call from client or server if you need more control.

Learn more here →

💨 Tailwind support​

Tailwind CSS framework is now supported in Wasp. Just add two files to the project and you’re ready to go!

Learn more here →

⏳ Async jobs/workers​

Developers can run one-time or schedule repeating functions that run out of the regular request-response band. This is useful for e.g. sending emails, crunching data, generating reports and other resources intensive tasks. Powered by pg-boss, zero setup required.

Learn more here →

🥛 Optimistic updates support​

Wasp will by default propagate your data model changes across the stack. Still, in some cases +

+

Wasp is in Beta: Auth, TypeScript, Tailwind, LSP

· 3 min read
Matija Sosic

Wasp is a simple configuration language for building full-stack web apps with less code and ensured best practices. It integrates with React, Node.js and Prisma and provides a lot of common features (auth, CRUD, async jobs, ...) out of the box.

Today, we’re moving to Beta.

Since the launch of Wasp Alpha in February 2021, we’ve been fortunate to work with hundreds of early adopters who helped us shape the product and prioritise the features to build. Number of applications have been deployed to production and even the first revenue generating product was built on top of Wasp.

Alpha in numbers​

  • 1,011 projects created
  • 2,012 GitHub stars
  • 45 GitHub contributors
  • 243 issues closed
  • 42,170 lines of code

Here are the the new features that ship with Beta:

🟦 TypeScript support​

Developers can now write all their code in TypeScript both on client and server. We’re also in the process of migrating our codebase and adding new types to Wasp imports every day.

Learn more here →

🔑 Full-stack authentication​

Besides username & password, Wasp now also supports authentication with Google. We offer both UI helpers (forms you can just import) and functions you can call from client or server if you need more control.

Learn more here →

💨 Tailwind support​

Tailwind CSS framework is now supported in Wasp. Just add two files to the project and you’re ready to go!

Learn more here →

⏳ Async jobs/workers​

Developers can run one-time or schedule repeating functions that run out of the regular request-response band. This is useful for e.g. sending emails, crunching data, generating reports and other resources intensive tasks. Powered by pg-boss, zero setup required.

Learn more here →

🥛 Optimistic updates support​

Wasp will by default propagate your data model changes across the stack. Still, in some cases you might want more control over that flow for the sake of smoother UX - that is now easy to achieve with Wasp.

Learn more here →

📟 Wasp Language Server​

Wasp now has its own LSP for VS Code (other editors coming soon) - that means improved syntax highlighting, code snippets, autocompletion, and error reporting.

Learn more here →

What’s next?​

The next features are going to be about making Wasp easier to use - more examples, starter templates and UI helpers. Longer term, we’ll look into deeper integration of data models throughout the stack and supporting more functionalities through the DSL.

It’s Beta Launch Week and we’re highlighting a new feature every week. Also, at the end of the week we’ll kick-off first Wasp hackathon! Signup here to stay in the loop.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2022/11/30/optimistic-update-feature-announcement.html b/blog/2022/11/30/optimistic-update-feature-announcement.html index 17bb6c944e..52139fa7a0 100644 --- a/blog/2022/11/30/optimistic-update-feature-announcement.html +++ b/blog/2022/11/30/optimistic-update-feature-announcement.html @@ -19,16 +19,16 @@ - - + + -
-

Feature Release Announcement - Wasp Optimistic Updates

· 7 min read
Filip Sodić

We’re excited to announce that Wasp actions now feature native support for optimistic updates! +

+

Feature Release Announcement - Wasp Optimistic Updates

· 7 min read
Filip Sodić

We’re excited to announce that Wasp actions now feature native support for optimistic updates! Continue reading to to find out what optimistic updates are and how Wasp implements them.

Wasp TS support

What are Optimistic Updates Anyway?​

Think about an interactive web app you use daily. It could be almost anything (e.g., Reddit, Youtube, Facebook). It almost certainly features UI elements you can interact with without refreshing the page, such as upvotes on Reddit or likes on Youtube.

All these small actions play out in the same manner. Let's look at Reddit upvotes as an example:

  1. You click on the upvote button
  2. Your browser sends a request to the server to save the upvote
  3. The server saves your upvote to the database and sends a successful response to your browser
  4. Your browser receives the successful response and reflects the change in the UI (i.e., you see your upvote)

The client waits for the server's confirmation before updating the UI because actions can sometimes fail. Well, at least that was the original idea.

These days, many popular websites update their UIs without waiting for servers' responses. Most of the time, everything goes as expected: you click on an upvote, and the server returns a successful response a couple of seconds later (depending on how fast your connection is). Since programmers want their users to have a snappier experience, instead of waiting for a confirmation, they update the UI immediately (as if the action were successful) and then roll back if the server doesn't return a successful response (which rarely happens). This pattern of optimistically updating the UI before receiving the confirmation of success is called, you guessed it, an Optimistic Update.

Most popular modern websites use optimistic updates to some degree. As mentioned, Reddit uses them for upvotes and downvotes, Youtube uses them for likes, and Trello uses them when moving cards between lists.

Optimistic updates are a significant UX improvement, but since they introduce additional state (which can get out of sync with the server), they can be tricky to get right. Then there's also the issue of writing additional code for managing the cache and rolling back the changes if the request ends up failing. Luckily, we're here to help!

Wasp recently added native support for optimistic updates, and the rest of this post demonstrates how to quickly set it up in your Wasp application.

A Wasp Todo App Without Optimistic Updates​

To honor the tradition of demonstrating UIs using Todo apps, We'll show you how to improve the UX of toggling an item's status when working with a slow connection. Before looking at our todo app in action, let's see how we've implemented it in Wasp.

These are the relevant declarations in our .wasp file:

main.wasp
entity Task {=psl
    id          Int     @id @default(autoincrement())
    description String
    isDone      Boolean @default(false)
psl=}

// A query for fetching all tasks.
query getTasks {
  fn: import { getTasks } from "@server/queries.js",
  entities: [Task]
}


// An action for updating the task's status.
action updateTask {
  fn: import { updateTask } from "@server/actions.js",
  entities: [Task]
}

This is the query we use to fetch the tasks (together with their statuses):

queries.js
export const getTasks = async (args, context) => {
  return context.entities.Task.findMany()
}

Here's the action we use to update a task’s status:

actions.js
export const updateTask = async ({ id, isDone }, context) => {
  return context.entities.Task.updateMany({
    where: { id },
    data: { isDone }
  })
}

Finally, this is how our client uses this action to update a task:

MainPage.js
import updateTask from '@wasp/queries'

// ...

function Task({ id, isDone, description }) {
  return (
    <div className="task">
      <label className="description">
        <input
          type='checkbox' id={id}
          checked={isDone}
          onChange={
            (e) => updateTask({ id, isDone: e.target.checked })
          }
        /><span>{description}</span></label>
    </div>
  )
}

Let's first see how updating a task looks when everything works as expected (i.e., we're on a fast connection):

Normal todo list

So far, so good! But what happens when our connection is not as fast?

Todo list with lag

Hmm, this isn't quite as smooth as we'd like it to be. The user has to wait for several seconds before seeing their their changes reflected by the UI.

How can we improve it? Well, of course, we can optimistically update the checkbox!

Performing a Wasp Action Optimistically​

To perform the updateTask action optimistically, all we need to do is decorate the calling code on the client:

MainPage.js
import updateTask from '@wasp/queries'

// ...

function Task({ id, isDone, description }) {
  const updateTaskOptimistically = useAction(updateTask, {
    optimisticUpdates: [{
      // Addressing the query we want to update.
      getQuerySpecifier: () => [getTasks],
      // Telling Wasp how to update the addressed query using the new payload
      // and the previously cached data.
      updateQuery: ({ id, isDone }, oldTasks) => oldTasks.map(
        task => task.id === id ? { ...task, isDone } : task
      )
    }]
  })

  return (
    <div className="task">
      <label className="description">
        <input
          type='checkbox' id={id}
          checked={isDone}
          onChange={
            (e) => updateTaskOptimistically({ id, isDone: e.target.checked })
          }
        /><span>{description}</span></label>
    </div>
  )
}

Those are all the changes we need, the rest of the code (i.e., main.wasp, queries.js and actions.js) remains the same. We won't describe the API in detail, but if you're curious, everything is covered by our official docs.

Finally, let's see how this version of the app looks in action:

Optimistically updated todo list

Our app no longer waits for the server before rendering the changes. Instead, it updates the cache optimistically, continues waiting for the response, and rolls back the changes if the action fails (Wasp internally handles all of this). As previously mentioned, simple changes such as this one rarely fail. Therefore, most of the time, the user enjoys their snappier experience without ever knowing anything special is happening in the background.

What Makes Optimistic Updates Difficult​

There's an old software engineering joke you're probably familiar with:

There are only two hard things in Computer Science: cache invalidation and naming things.

Optimistically updating a query involves plenty of meddling with the client-side cache, which is bound to come with a few gotchas. Examples include the answers to questions such as:

  • What happens when an optimistically updated action fails?
  • What happens when the user uses the optimistically updated data in a new action?
  • What happens when the user performs a different action that affects the same cached data as the optimistically updated one?
  • etc.

Notice how Wasp users don't need to know about any of these issues when using our optimistic updates API. They only need to tell Wasp which query they wish to update and how, and Wasp takes care of the rest.

Wasp internally uses React Query, an excellent asynchronous state management library we'll gladly recommend to anyone. While React Query does solve some of these problems and helps with some of the rest, we still had to implement quite a complex mechanism to fully cover all edge cases.

Describing this mechanism, although technically interesting, is beyond the scope of a feature announcement. But stay tuned because in a future blog post, we'll be taking a deep dive into the infrastructure Wasp uses to ensure optimistic updates are performed correctly and consistently.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2022/12/01/beta-ide-improvements.html b/blog/2022/12/01/beta-ide-improvements.html index 92a3016c1f..24e908f615 100644 --- a/blog/2022/12/01/beta-ide-improvements.html +++ b/blog/2022/12/01/beta-ide-improvements.html @@ -19,13 +19,13 @@ - - + + -
-

Wasp Beta brings major IDE improvements

· 6 min read
Martin Sosic

With the Beta release (0.7), Wasp brings its IDE game to a whole new level!

So far Wasp didn’t have much beyond basic syntax highlighting in VSCode, but now it has:

  1. Wasp language server, that brings the following to your .wasp files:
    1. live error reporting in your editor
    2. autocompletion (basic for now)
  2. VSCode Wasp language extension:
    1. snippets (for page, query, action, entity)
    2. improved syntax highlighting for .wasp files
    3. integration with the above-mentioned language server
  3. Support for popular IDEs to fully support Javascript and Typescript files in the Wasp project.

Wasp IDE support in action in VSCode: syntax highlighting, snippets, live error reporting.

Wasp IDE support in action in VSCode: syntax highlighting, snippets, live error reporting.

Wasp Language Server

Wasp Language Server (WLS) is the “brain” behind smart IDE features like live error reporting and autocompletion - so if it seems like IDE actually understands your code to some degree, well that is the language server!

tip

For curious, check out the source code of WLS on Github: https://github.com/wasp-lang/wasp/tree/main/waspc/waspls/src/Wasp/LSP .

Features​

Live error/warning reporting​

WLS compiles wasp code for you as you work on it and shows you any errors directly in the editor, via red squiggly lines.

Autocompletion​

WLS understands at which part of code you are right now and offers appropriate completions for it.

note

Right now WLS is pretty naive here, and mostly focuses on offering available expressions when it realizes you need an expression. This is helpful but just a start, and it will get much smarter in future versions!

Bit of history: why are Language Servers cool​

Years ago, there was no standardized way to write something like Language Server for your language, instead, each language was doing something of its own, and then each editor/IDE would also implement its own layer of logic for using it, and that was a loooot of work that needed to be done for each editor!

Luckily, Microsoft then came up with Language Server Protocol - a standardized way of communicating between the “smart” part, implemented by language creators, and the editor/IDE part (language extension) that is using it. This enabled each editor to implement this logic for interacting with language servers only once, and then it can be used for any language server!

This is great for us, language creators, because it means that once we implement a language server for our language, most of the work is done, and the work we need to do per each editor is manageable.

Right now WLS is used only by the VSCode Wasp language extension, but thanks to the nature of the Language Server Protocol, it should be relatively easy to add support for other editors too! Check this GH issue if you are interested in helping.

Setup​

The best thing: there is nothing you, as a Wasp user, have to do to set up WLS! It already comes bundled with your installation of wasp → so if you can run wasp projects on your machine, you already have WLS, and it is always of the correct version needed for your current wasp installation. The only thing you need to ensure is you have wasp version ≥ 0.6, and a relatively fresh VSCode Wasp language extension.

An easy way to check that your version of wasp has WLS packaged into it is to run it and look at its usage instructions: it should mention waspls as one of the commands.

Wasp VSCode extension

If we would call Wasp Language Server (WLS) the “backend”, then VSCode Wasp language extension would be “frontend” → it takes care of everything to ensure you have a nice experience working with Wasp in VSCode, while delegating the hardest work to the WLS.

tip

For curious, you can check out its source code here, core of it is just one file: https://github.com/wasp-lang/vscode-wasp/blob/main/src/extension.ts

Features​

Syntax highlighting​

Nothing unexpected here: it recognizes different parts of Wasp syntax, like type, value, identifier, comment, string, … and colors them appropriately.

If you are curious how is this implemented, check https://github.com/wasp-lang/vscode-wasp/blob/main/syntaxes/wasp.tmLanguage.yaml → the whole syntax of Wasp is described via this “mysterious” old TextMate format, since that is the way to do it in VSCode.

Snippets​

Wasp allows you to quickly generate a snippet of code for a new page, query, action, or entity!

Check out our snippet definitions here: https://github.com/wasp-lang/vscode-wasp/blob/main/snippets/wasp.json . It is actually really easy, in VSCode, to define them and add new ones.

Live error reporting + autocompletion​

This is done by delegating the work to WLS, as described above!

IDE support for Javascript / Typescript in Wasp project

Due to how unique Wasp is in its approach, getting an IDE to provide all the usual features for Javascript / Typescript wasn’t completely working, and instead, the IDE would get somewhat confused with the context in which files are and would for example not be able to offer “go to definition” for some values, or would not know how to follow the import path.

With Wasp Beta this is now resolved! We resolved this by somewhat changing the structure of the Wasp project and also adding tsconfig.json files that provide IDE with the information needed to correctly analyze the JS/TS source files.

To learn more about Typescript support in Wasp Beta, check this blog post!

What does the future hold?

While Wasp Beta greatly improved IDE support for Wasp, there are still quite a few things we want to improve on:

  1. Smarter autocompletion via WLS.
    1. Right now it suggests any expression when you need an expression. In the future, we want it to know exactly what is the type of needed expression, and suggest only expressions of that type! So if I am in route ... { to: <my_cursor_here> }, then I want to see only pages among the suggested completions, not queries or actions or something else.
    2. Further, we would also like it to autocomplete on dictionary fields → so if I am in route ... { <my_cursor_here> }, it should offer me path and to as completions, as those are only valid fields in the route dictionary.
  2. Extensions for other editors besides VSCode. Now that we have Wasp Language Server, these shouldn’t be too hard to implement! This is also a great task for potential contributors: check this GH issue if you are interested.
  3. Implement Wasp code formatter. We could make it a part of WLS, and then have the editor extension call it on save.
  4. Improve support for PSL (Prisma Schema Language) in .wasp files.

If any of these sound interesting, feel free to join us on our Github, or join the discussion on Discord!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Wasp Beta brings major IDE improvements

· 6 min read
Martin Sosic

With the Beta release (0.7), Wasp brings its IDE game to a whole new level!

So far Wasp didn’t have much beyond basic syntax highlighting in VSCode, but now it has:

  1. Wasp language server, that brings the following to your .wasp files:
    1. live error reporting in your editor
    2. autocompletion (basic for now)
  2. VSCode Wasp language extension:
    1. snippets (for page, query, action, entity)
    2. improved syntax highlighting for .wasp files
    3. integration with the above-mentioned language server
  3. Support for popular IDEs to fully support Javascript and Typescript files in the Wasp project.

Wasp IDE support in action in VSCode: syntax highlighting, snippets, live error reporting.

Wasp IDE support in action in VSCode: syntax highlighting, snippets, live error reporting.

Wasp Language Server

Wasp Language Server (WLS) is the “brain” behind smart IDE features like live error reporting and autocompletion - so if it seems like IDE actually understands your code to some degree, well that is the language server!

tip

For curious, check out the source code of WLS on Github: https://github.com/wasp-lang/wasp/tree/main/waspc/waspls/src/Wasp/LSP .

Features​

Live error/warning reporting​

WLS compiles wasp code for you as you work on it and shows you any errors directly in the editor, via red squiggly lines.

Autocompletion​

WLS understands at which part of code you are right now and offers appropriate completions for it.

note

Right now WLS is pretty naive here, and mostly focuses on offering available expressions when it realizes you need an expression. This is helpful but just a start, and it will get much smarter in future versions!

Bit of history: why are Language Servers cool​

Years ago, there was no standardized way to write something like Language Server for your language, instead, each language was doing something of its own, and then each editor/IDE would also implement its own layer of logic for using it, and that was a loooot of work that needed to be done for each editor!

Luckily, Microsoft then came up with Language Server Protocol - a standardized way of communicating between the “smart” part, implemented by language creators, and the editor/IDE part (language extension) that is using it. This enabled each editor to implement this logic for interacting with language servers only once, and then it can be used for any language server!

This is great for us, language creators, because it means that once we implement a language server for our language, most of the work is done, and the work we need to do per each editor is manageable.

Right now WLS is used only by the VSCode Wasp language extension, but thanks to the nature of the Language Server Protocol, it should be relatively easy to add support for other editors too! Check this GH issue if you are interested in helping.

Setup​

The best thing: there is nothing you, as a Wasp user, have to do to set up WLS! It already comes bundled with your installation of wasp → so if you can run wasp projects on your machine, you already have WLS, and it is always of the correct version needed for your current wasp installation. The only thing you need to ensure is you have wasp version ≥ 0.6, and a relatively fresh VSCode Wasp language extension.

An easy way to check that your version of wasp has WLS packaged into it is to run it and look at its usage instructions: it should mention waspls as one of the commands.

Wasp VSCode extension

If we would call Wasp Language Server (WLS) the “backend”, then VSCode Wasp language extension would be “frontend” → it takes care of everything to ensure you have a nice experience working with Wasp in VSCode, while delegating the hardest work to the WLS.

tip

For curious, you can check out its source code here, core of it is just one file: https://github.com/wasp-lang/vscode-wasp/blob/main/src/extension.ts

Features​

Syntax highlighting​

Nothing unexpected here: it recognizes different parts of Wasp syntax, like type, value, identifier, comment, string, … and colors them appropriately.

If you are curious how is this implemented, check https://github.com/wasp-lang/vscode-wasp/blob/main/syntaxes/wasp.tmLanguage.yaml → the whole syntax of Wasp is described via this “mysterious” old TextMate format, since that is the way to do it in VSCode.

Snippets​

Wasp allows you to quickly generate a snippet of code for a new page, query, action, or entity!

Check out our snippet definitions here: https://github.com/wasp-lang/vscode-wasp/blob/main/snippets/wasp.json . It is actually really easy, in VSCode, to define them and add new ones.

Live error reporting + autocompletion​

This is done by delegating the work to WLS, as described above!

IDE support for Javascript / Typescript in Wasp project

Due to how unique Wasp is in its approach, getting an IDE to provide all the usual features for Javascript / Typescript wasn’t completely working, and instead, the IDE would get somewhat confused with the context in which files are and would for example not be able to offer “go to definition” for some values, or would not know how to follow the import path.

With Wasp Beta this is now resolved! We resolved this by somewhat changing the structure of the Wasp project and also adding tsconfig.json files that provide IDE with the information needed to correctly analyze the JS/TS source files.

To learn more about Typescript support in Wasp Beta, check this blog post!

What does the future hold?

While Wasp Beta greatly improved IDE support for Wasp, there are still quite a few things we want to improve on:

  1. Smarter autocompletion via WLS.
    1. Right now it suggests any expression when you need an expression. In the future, we want it to know exactly what is the type of needed expression, and suggest only expressions of that type! So if I am in route ... { to: <my_cursor_here> }, then I want to see only pages among the suggested completions, not queries or actions or something else.
    2. Further, we would also like it to autocomplete on dictionary fields → so if I am in route ... { <my_cursor_here> }, it should offer me path and to as completions, as those are only valid fields in the route dictionary.
  2. Extensions for other editors besides VSCode. Now that we have Wasp Language Server, these shouldn’t be too hard to implement! This is also a great task for potential contributors: check this GH issue if you are interested.
  3. Implement Wasp code formatter. We could make it a part of WLS, and then have the editor extension call it on save.
  4. Improve support for PSL (Prisma Schema Language) in .wasp files.

If any of these sound interesting, feel free to join us on our Github, or join the discussion on Discord!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2022/12/08/fast-fullstack-chatgpt.html b/blog/2022/12/08/fast-fullstack-chatgpt.html index 518287f0d3..35bf84704b 100644 --- a/blog/2022/12/08/fast-fullstack-chatgpt.html +++ b/blog/2022/12/08/fast-fullstack-chatgpt.html @@ -19,13 +19,13 @@ - - + + -
-

Watch us build a *truly* full-stack app in just 9 minutes w/ Wasp & ChatGPT 🚀 🤯

· 3 min read
Vinny

​

There’s a lot of hype around ChatGPT at the moment, and for good reason. It’s amazing. But there’s also some very valid criticism: that it’s simply taking the grunt work out of programming by writing boilerplate for us, which we as developers have to maintain!

I expected technology to make programming less laborious, as it does to most things. But I have to admit I expected it to happen by programmers switching to more powerful languages, rather than continuing to write programs full of boilerplate, but having AIs generate most of it.

PG is totally right in his remark above, but what he doesn’t realize is that there are languages out there that attempt to overcome this very problem, and Wasp is one of them.

What makes Wasp unique is that it’s a framework that uses a super simple language to help you build your web app: front-end, server, and deployment. But it’s not a complicated language like Java or Python, it’s more similar to SQL or JSON, so the learning curve is really quick (technically, it’s a Domain Specific Langauge or DSL).

Check it out for yourself:

main.wasp
app todoApp {
  title: "ToDo App",/* visible in tab */

  auth: {/* full-stack auth out-of-the-box */
    userEntity: User,
    externalAuthEntity: SocialLogin,
    methods: {
      usernameAndPassword: {},
      google: {}
    }
  }
}

route RootRoute { path: "/", to: MainPage }
page MainPage {
    /* import your React code */
  component: import Main from "@client/Main.js"
}

With this simple file above, Wasp will continually compile a truly full-stack web app for you, with a React front-end, and an ExpressJS server. You’re free to then build out the important features yourself with React, NodeJS, Prisma, and react-query.

The great part is, you can probably understand the Wasp syntax without even referencing the docs. Which means AI can probably work with it easily as well. So rather than having AI create a ton of boilerplate for us, we thought “can ChatGPT write Wasp?” If it can, all we need is to have it create that one file, and then the power of Wasp will take care of the rest. No more endless boilerplate!

So that’s exactly what we set to find out in the video above. The results? Well let’s just say they speak for themselves.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Watch us build a *truly* full-stack app in just 9 minutes w/ Wasp & ChatGPT 🚀 🤯

· 3 min read
Vinny

​

There’s a lot of hype around ChatGPT at the moment, and for good reason. It’s amazing. But there’s also some very valid criticism: that it’s simply taking the grunt work out of programming by writing boilerplate for us, which we as developers have to maintain!

I expected technology to make programming less laborious, as it does to most things. But I have to admit I expected it to happen by programmers switching to more powerful languages, rather than continuing to write programs full of boilerplate, but having AIs generate most of it.

PG is totally right in his remark above, but what he doesn’t realize is that there are languages out there that attempt to overcome this very problem, and Wasp is one of them.

What makes Wasp unique is that it’s a framework that uses a super simple language to help you build your web app: front-end, server, and deployment. But it’s not a complicated language like Java or Python, it’s more similar to SQL or JSON, so the learning curve is really quick (technically, it’s a Domain Specific Langauge or DSL).

Check it out for yourself:

main.wasp
app todoApp {
  title: "ToDo App",/* visible in tab */

  auth: {/* full-stack auth out-of-the-box */
    userEntity: User,
    externalAuthEntity: SocialLogin,
    methods: {
      usernameAndPassword: {},
      google: {}
    }
  }
}

route RootRoute { path: "/", to: MainPage }
page MainPage {
    /* import your React code */
  component: import Main from "@client/Main.js"
}

With this simple file above, Wasp will continually compile a truly full-stack web app for you, with a React front-end, and an ExpressJS server. You’re free to then build out the important features yourself with React, NodeJS, Prisma, and react-query.

The great part is, you can probably understand the Wasp syntax without even referencing the docs. Which means AI can probably work with it easily as well. So rather than having AI create a ton of boilerplate for us, we thought “can ChatGPT write Wasp?” If it can, all we need is to have it create that one file, and then the power of Wasp will take care of the rest. No more endless boilerplate!

So that’s exactly what we set to find out in the video above. The results? Well let’s just say they speak for themselves.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/01/11/betathon-review.html b/blog/2023/01/11/betathon-review.html index 0cf678534d..e6cc65fec8 100644 --- a/blog/2023/01/11/betathon-review.html +++ b/blog/2023/01/11/betathon-review.html @@ -19,13 +19,13 @@ - - + + -
-

Hosting Our First Hackathon: Results & Review

· 6 min read
Vinny

To finalize the Wasp Beta launch week, we held a Beta Hackathon, which we dubbed the “Betathon”. The idea was to hold a simple, open, and fun hackathon to encourage users to build with Wasp, and that’s exactly what they did!

As Wasp is still in its early days, we weren’t sure what the response would be, or if there’d be any response at all. Considering that we didn’t do much promotion of the Hackathon outside of our own channels, we were surprised by the results.

In this post, I’ll give you a quick run-down of:

  • the hackathon results 🏆
  • how the hackathon was organized
  • how we promoted it
  • the community response

…and the Winners Are:​

What’s a hackathon without the participants!? Let’s get this post off to a proper start by congratulating our winners and showcasing their work. 🔍

🥇 Tim’s Job Board​

Tim's Job Board

Tim really went for it and created a feature-rich Job Board:

“Wasp is very awesome! Easy setup and start-up especially if you're familiar with the Prisma ORM and Tailwind CSS. The stack is small but powerful... I'm going to use Wasp on a few MVP projects this year.” - Tim

🥈Chris’s “Cook Wherever” Recipes App​

Chris's Cook Wherever Recipes App

Chris created an extensive database of recipes in a slick app:

“This was the best app dev experience I ever had! …Walking through the docs, I immediately figured out how to use Wasp and was able to make a prototype in a couple of days.” - Chris

🥉 Richard’s Roadmap & Feature Voting App​

Richard’s Roadmap & Feature Voting App

“I liked how Wasp simplified writing query/actions that are used to interact with the backend and frontend. How everything is defined and configured in wasp file and just works. Also […] login/signup was really easy to do since Wasp provides these two methods for use.” -

🥉 Emmanuel’s Notes App​

Emmanuel’s Notes App

I joined the hackathon less than 48 hours before the submission deadline. Wasp made it look easy because it handled the hard parts for me. For example, username/password authentication took less than 7 lines of code to implement. - excerpt from Emmanuel’s Betathon Blog Post

Hackathon How-to​

Personally, I’ve never organized a hackathon before, and this was Wasp’s first hackathon as well, so when you’re a complete newbie at something, you often look towards others for inspiration. Being admirers of the work and style of Supabase, we drew a lot of inspiration from their “launch week” approach when preparing for our own Beta launch and hacakthon.

Wasp Betathon Homepage
Our dedicated hackathon landing page w/ intro video & submission form

With some good inspiration in hand, we set off to create a simple, easy-going Hackathon experience. We weren’t certain we’d get many participants, so we decided to make the process as open as possible: two weeks to work on any project using Wasp, alone or in a team of up to 4 people, submitted on our Betathon Homepage before the deadline. That was it.

When you’re an early-stage startup, you can’t offer big cash prizes, so we asked Railway if they’d be interested in sponsoring some prizes, as we’re big fans of their deployment and hosting platform. Luckily, they agreed (thanks, Railway 🙏🚂). It was also a great match, since we already had the documentation for deploying Wasp apps to Railway on our website, making it an obvious choice for the participants to deploy their Hackathon apps with.

Keyboard
Disclaimer: actual prize keyboard will be cooler and waspier 😎🐝

On top of that, we decided that a cool grand prize could be a Wasp-colored mechanical keyboard. Nothing fancy, but keyboards are an item a lot of programmers love. We also threw in some Wasp beanies and shirts, and stated that we’d spotlight the winner’s on our platforms and social media accounts.

Promotion​

For the Wasp Beta Launch Week, we were active and publicising Wasp on many platforms. We didn’t outright promote the hackathon on those platforms, but we were getting a lot of incoming interest to our Website and Discord, so we made noise about it there. We posted banners on the homepage, and made announcements on Discord and Twitter that directed people to a Beta Hacakthon homepage we created.

The homepage was nice to have as a central spot for all the rules and relevant info. We also added a fun intro video to give the hackathon a more personal touch. I also think the effort put into making an intro video gives participants the feeling that they’re entering into a serious contest and committing to something of substance.

Hackathon Wasp app repo
Wanna host your own Hackathon? Use our template app!

As an extra bonus, we wrote the Betathon Homepage with Wasp, and put the source code up on our GitHub. We thought it might inspire people to build with Wasp, using it as a guide while creating their own projects for the hackathon, plus it could be used by others in the future if they want to host their own hackathon. 💻

The Response​

The response overall was small but significant, considering Wasp’s age. We were also extremely happy with the quality of the engagement. We had thirteen participants register overall, a nice number considering we only started promoting the hackathon on the day that we announced it (this is probably something we’d do differently next time)!

We also asked participants for their feedback on participating in the Hackathon, and they were all pleased with the open, straight-forward approach we took, so we’ll most likely be repeating this for future versions. Other good signs were the many comments that participants were eager to take part in our next hackathon, as well as some dedicated new community members, which makes it all the more motivating for us. 💪

A big THANK YOU again to all the participants for their hard work and feedback. Here’s to the next one! 🍻

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Hosting Our First Hackathon: Results & Review

· 6 min read
Vinny

To finalize the Wasp Beta launch week, we held a Beta Hackathon, which we dubbed the “Betathon”. The idea was to hold a simple, open, and fun hackathon to encourage users to build with Wasp, and that’s exactly what they did!

As Wasp is still in its early days, we weren’t sure what the response would be, or if there’d be any response at all. Considering that we didn’t do much promotion of the Hackathon outside of our own channels, we were surprised by the results.

In this post, I’ll give you a quick run-down of:

  • the hackathon results 🏆
  • how the hackathon was organized
  • how we promoted it
  • the community response

…and the Winners Are:​

What’s a hackathon without the participants!? Let’s get this post off to a proper start by congratulating our winners and showcasing their work. 🔍

🥇 Tim’s Job Board​

Tim's Job Board

Tim really went for it and created a feature-rich Job Board:

“Wasp is very awesome! Easy setup and start-up especially if you're familiar with the Prisma ORM and Tailwind CSS. The stack is small but powerful... I'm going to use Wasp on a few MVP projects this year.” - Tim

🥈Chris’s “Cook Wherever” Recipes App​

Chris's Cook Wherever Recipes App

Chris created an extensive database of recipes in a slick app:

“This was the best app dev experience I ever had! …Walking through the docs, I immediately figured out how to use Wasp and was able to make a prototype in a couple of days.” - Chris

🥉 Richard’s Roadmap & Feature Voting App​

Richard’s Roadmap & Feature Voting App

“I liked how Wasp simplified writing query/actions that are used to interact with the backend and frontend. How everything is defined and configured in wasp file and just works. Also […] login/signup was really easy to do since Wasp provides these two methods for use.” -

🥉 Emmanuel’s Notes App​

Emmanuel’s Notes App

I joined the hackathon less than 48 hours before the submission deadline. Wasp made it look easy because it handled the hard parts for me. For example, username/password authentication took less than 7 lines of code to implement. - excerpt from Emmanuel’s Betathon Blog Post

Hackathon How-to​

Personally, I’ve never organized a hackathon before, and this was Wasp’s first hackathon as well, so when you’re a complete newbie at something, you often look towards others for inspiration. Being admirers of the work and style of Supabase, we drew a lot of inspiration from their “launch week” approach when preparing for our own Beta launch and hacakthon.

Wasp Betathon Homepage
Our dedicated hackathon landing page w/ intro video & submission form

With some good inspiration in hand, we set off to create a simple, easy-going Hackathon experience. We weren’t certain we’d get many participants, so we decided to make the process as open as possible: two weeks to work on any project using Wasp, alone or in a team of up to 4 people, submitted on our Betathon Homepage before the deadline. That was it.

When you’re an early-stage startup, you can’t offer big cash prizes, so we asked Railway if they’d be interested in sponsoring some prizes, as we’re big fans of their deployment and hosting platform. Luckily, they agreed (thanks, Railway 🙏🚂). It was also a great match, since we already had the documentation for deploying Wasp apps to Railway on our website, making it an obvious choice for the participants to deploy their Hackathon apps with.

Keyboard
Disclaimer: actual prize keyboard will be cooler and waspier 😎🐝

On top of that, we decided that a cool grand prize could be a Wasp-colored mechanical keyboard. Nothing fancy, but keyboards are an item a lot of programmers love. We also threw in some Wasp beanies and shirts, and stated that we’d spotlight the winner’s on our platforms and social media accounts.

Promotion​

For the Wasp Beta Launch Week, we were active and publicising Wasp on many platforms. We didn’t outright promote the hackathon on those platforms, but we were getting a lot of incoming interest to our Website and Discord, so we made noise about it there. We posted banners on the homepage, and made announcements on Discord and Twitter that directed people to a Beta Hacakthon homepage we created.

The homepage was nice to have as a central spot for all the rules and relevant info. We also added a fun intro video to give the hackathon a more personal touch. I also think the effort put into making an intro video gives participants the feeling that they’re entering into a serious contest and committing to something of substance.

Hackathon Wasp app repo
Wanna host your own Hackathon? Use our template app!

As an extra bonus, we wrote the Betathon Homepage with Wasp, and put the source code up on our GitHub. We thought it might inspire people to build with Wasp, using it as a guide while creating their own projects for the hackathon, plus it could be used by others in the future if they want to host their own hackathon. 💻

The Response​

The response overall was small but significant, considering Wasp’s age. We were also extremely happy with the quality of the engagement. We had thirteen participants register overall, a nice number considering we only started promoting the hackathon on the day that we announced it (this is probably something we’d do differently next time)!

We also asked participants for their feedback on participating in the Hackathon, and they were all pleased with the open, straight-forward approach we took, so we’ll most likely be repeating this for future versions. Other good signs were the many comments that participants were eager to take part in our next hackathon, as well as some dedicated new community members, which makes it all the more motivating for us. 💪

A big THANK YOU again to all the participants for their hard work and feedback. Here’s to the next one! 🍻

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/01/18/wasp-beta-update-dec.html b/blog/2023/01/18/wasp-beta-update-dec.html index ba6e3bc090..3896662b60 100644 --- a/blog/2023/01/18/wasp-beta-update-dec.html +++ b/blog/2023/01/18/wasp-beta-update-dec.html @@ -19,14 +19,14 @@ - - + + -
-

Wasp Beta December 2022

· 6 min read
Matija Sosic

Wasp Update Dec 22

Want to stay in the loop? → Join our newsletter!

Hey Wasp tribe 🐝 ,

Happy New Year! I know you're probably already sick of hearing it, but hopefully we're the last ones to congratulate you 🔫 👈 (that's pistol fingers emoji in case you were wondering).

Pistol fingers
This is how I imagine myself telling the joke above.

Now that the Beta Launch craze is over (thanks for your support, it was amazing - we saw more devs hacking with Wasp than ever!), we're back to our usual programming. Let's dive in and see what's new and what's in the plans for this year:

🎮 🐝 We hosted our first hackathon - it was a blast! 🎉 🎉​

Tweet about Wasp

We launched our first Wasp hackathon ever on the last day of Beta Launch (thus we named it Betathon) and got some really cool submissions! Winners received hosting credits kindly offered by our partners at Railway and a special 1st place award was a wasp-themed mechanical keyboard (we're still assembling it but we'll post photos on our twitter :))!

“This was the best app dev experience I ever had! …Walking through the docs, I immediately figured out how to use Wasp and was able to make a prototype in a couple of days.” - Chris

To check out the winning projects and see where devs found Wasp most helpful, take a look here: Wasp Betathon review post

🔑 New auth method - GitHub! 🐙​

Next to username/password and Google, Wasp now also supports GitHub as an authentication method!

Support for GitHub auth in Wasp

Putting the code above in your main.wasp file and specifying your GitHub env variables is all you need to do! Wasp will provide you with a full-stack GitHub authentication along with UI helpers (GitHub sign-up button) you can immediately use in your React component.

For more details, check the docs here.

💬 Let's discuss - on GitHub Discussions!​

Wasp is now on GitHub Discussions

So far we've been capturing your feedback across GitHub issues and Wasp Discord server, but with the current volume it has become a bit unwieldy and hard to keep track of.

That's why we introduced Wasp GitHub Discussions! It's a relatively new service by GitHub that allows distinguishing between specific, well-defined issues (bug reports, TODOs, ...) and discussion items (ideating about new features, figuring out best practices, etc) and allows for upvotes from the community.

If there is a feature you'd like to see in Wasp (e.g. support for Vue) you can create a new post for it or upvote it if it is already there!

🚀 Next launch is coming - a super early sneak peek 👀​

Next launch sneak peek

We know we just wrapped up Beta release, but we are busy wasps and our heads are already in the next one! We made a preliminary draft of the features that are going to be included - the "theme" of this release is going to be about making Wasp super easy and friendly for you to use.

We'll further polish our auth & deployment experience, along with ensuring TypeScript experience is fully typed and as helpful as possible. Stay tuned for the official roadmap and date of the next launch!

Want to make sure your fav feature makes it into the next release? Let us know on Discussions!

🎥 Wasp is now on YouTube!​

Wasp is on YouTube

Thanks to Vince, who recently joined as Devrel (intro blog post coming soon!), Wasp now finally has its YouTube channel!

We're just starting out but already made some splashes - our "Build a full-stack app in 9 mins with Wasp and ChatGPT" got over 2k views (not bad for a channel with 50 subscribers, right?).

We also made our first YT short, featuring how to add auth to your app in 60 seconds with Wasp.

If you want to stay in the loop (and I guess you do since you're reading this :D), please subscribe to our channel and help us reach the first 100 subscribers on YouTube!

Subscribe to Wasp on YouTube
You know you want it!

🕹 Community highlights​

Wasp Github Star Growth - over 2,000 ⭐️, woohoo!​

Beta was great and it brought us to 2,234 stars! We never imagined Wasp could become so popular when we were just getting started. Huge thanks to all our contributors and stargazers - you are amazing!

Wasp has over 2,000 GitHub stars

And if you haven't yet, please star us on Github! Yes, we are shameless star beggars, but if you believe in the project and want to support it that's one of the best ways to do it (next to actually building something with Wasp - go do that too! :D)

And before you leave, here's a photo of a squishy wasp (ok, it's a bumblebee, but you get it) proudly rocking Wasp swag 🤘 🐝 (yep, we got a bunch of these for the office, you can also see Martin the background :D)!

Wasp's new mascot
This lil' boy actually became pretty popular in our community - we're now looking for a name for him!

Thanks for reading and see you in a month!

Buzzity buzz, you got that pizzazz 🐝 🐝,
+

+

Wasp Beta December 2022

· 6 min read
Matija Sosic

Wasp Update Dec 22

Want to stay in the loop? → Join our newsletter!

Hey Wasp tribe 🐝 ,

Happy New Year! I know you're probably already sick of hearing it, but hopefully we're the last ones to congratulate you 🔫 👈 (that's pistol fingers emoji in case you were wondering).

Pistol fingers
This is how I imagine myself telling the joke above.

Now that the Beta Launch craze is over (thanks for your support, it was amazing - we saw more devs hacking with Wasp than ever!), we're back to our usual programming. Let's dive in and see what's new and what's in the plans for this year:

🎮 🐝 We hosted our first hackathon - it was a blast! 🎉 🎉​

Tweet about Wasp

We launched our first Wasp hackathon ever on the last day of Beta Launch (thus we named it Betathon) and got some really cool submissions! Winners received hosting credits kindly offered by our partners at Railway and a special 1st place award was a wasp-themed mechanical keyboard (we're still assembling it but we'll post photos on our twitter :))!

“This was the best app dev experience I ever had! …Walking through the docs, I immediately figured out how to use Wasp and was able to make a prototype in a couple of days.” - Chris

To check out the winning projects and see where devs found Wasp most helpful, take a look here: Wasp Betathon review post

🔑 New auth method - GitHub! 🐙​

Next to username/password and Google, Wasp now also supports GitHub as an authentication method!

Support for GitHub auth in Wasp

Putting the code above in your main.wasp file and specifying your GitHub env variables is all you need to do! Wasp will provide you with a full-stack GitHub authentication along with UI helpers (GitHub sign-up button) you can immediately use in your React component.

For more details, check the docs here.

💬 Let's discuss - on GitHub Discussions!​

Wasp is now on GitHub Discussions

So far we've been capturing your feedback across GitHub issues and Wasp Discord server, but with the current volume it has become a bit unwieldy and hard to keep track of.

That's why we introduced Wasp GitHub Discussions! It's a relatively new service by GitHub that allows distinguishing between specific, well-defined issues (bug reports, TODOs, ...) and discussion items (ideating about new features, figuring out best practices, etc) and allows for upvotes from the community.

If there is a feature you'd like to see in Wasp (e.g. support for Vue) you can create a new post for it or upvote it if it is already there!

🚀 Next launch is coming - a super early sneak peek 👀​

Next launch sneak peek

We know we just wrapped up Beta release, but we are busy wasps and our heads are already in the next one! We made a preliminary draft of the features that are going to be included - the "theme" of this release is going to be about making Wasp super easy and friendly for you to use.

We'll further polish our auth & deployment experience, along with ensuring TypeScript experience is fully typed and as helpful as possible. Stay tuned for the official roadmap and date of the next launch!

Want to make sure your fav feature makes it into the next release? Let us know on Discussions!

🎥 Wasp is now on YouTube!​

Wasp is on YouTube

Thanks to Vince, who recently joined as Devrel (intro blog post coming soon!), Wasp now finally has its YouTube channel!

We're just starting out but already made some splashes - our "Build a full-stack app in 9 mins with Wasp and ChatGPT" got over 2k views (not bad for a channel with 50 subscribers, right?).

We also made our first YT short, featuring how to add auth to your app in 60 seconds with Wasp.

If you want to stay in the loop (and I guess you do since you're reading this :D), please subscribe to our channel and help us reach the first 100 subscribers on YouTube!

Subscribe to Wasp on YouTube
You know you want it!

🕹 Community highlights​

Wasp Github Star Growth - over 2,000 ⭐️, woohoo!​

Beta was great and it brought us to 2,234 stars! We never imagined Wasp could become so popular when we were just getting started. Huge thanks to all our contributors and stargazers - you are amazing!

Wasp has over 2,000 GitHub stars

And if you haven't yet, please star us on Github! Yes, we are shameless star beggars, but if you believe in the project and want to support it that's one of the best ways to do it (next to actually building something with Wasp - go do that too! :D)

And before you leave, here's a photo of a squishy wasp (ok, it's a bumblebee, but you get it) proudly rocking Wasp swag 🤘 🐝 (yep, we got a bunch of these for the office, you can also see Martin the background :D)!

Wasp's new mascot
This lil' boy actually became pretty popular in our community - we're now looking for a name for him!

Thanks for reading and see you in a month!

Buzzity buzz, you got that pizzazz 🐝 🐝,
Matija, Martin and the Wasp team

Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2023/01/31/wasp-beta-launch-review.html b/blog/2023/01/31/wasp-beta-launch-review.html index 6f44161ecd..648cc2a4d6 100644 --- a/blog/2023/01/31/wasp-beta-launch-review.html +++ b/blog/2023/01/31/wasp-beta-launch-review.html @@ -19,13 +19,13 @@ - - + + -
-

Convincing developers to try a new web framework - the effects of launching beta

· 7 min read
Matija Sosic

Alpha feedback

We are developing an OSS web framework in a form of a config language (DSL) that works with React & Node.js. Getting developers to use a new tool (especially a web framework) is a pretty hard thing to do. We wished there were more stories of how today's mainstream tools got adopted that we could learn from, so that motivated us to document our own.

Want to stay in the loop? → Join our newsletter!

TL;DR​

  • HackerNews launch post brought the most traffic, by far
  • Product Hunt launch went worse than expected, bots took over
  • Our goal was to reach GitHub Trending but we failed
  • Less overall traffic than for the Alpha launch, but much higher quality of feedback + a shift in public perception
  • Having a public launch date made us 3x more productive

📊 The results: stats​

We launched Beta on Nov 27, 2022 in a launch week format, recently popularized by Supabase. During the first week we launched on Product Hunt, and after the weekend we posted on HackerNews. Here's what the numbers were on the last day of the launch:

  • 190 GitHub stars added to the repo
  • 108 new projects started
  • 83 new users (installed Wasp locally and ran it)

Web visitors during beta launch week

HN launch caused almost 2x spike in traffic and usage. Also, although our launch week already ended by the start of December, we actually had the most users ever throughout December:

WAU displayed monthly

Looking back, this wasn't at all our biggest event in terms of traffic, but it was in terms of usage:

All time stats

One of the main effects of the launch (together with a few recent successful HN posts, and the Alpha Testing Program we ran in Jul '22) is that we managed to move the baseline WAU from ~10 to ~20. Another effect, felt more subjectively, is the change in the community perception.

Community perception shift​

As mentioned above, although our Alpha launch had higher absolute numbers (website traffic, HN upvotes etc), it felt that Beta launch caused the biggest perception shift in the community so far.

Before were mostly getting superficial comments like “this looks cool, I’ll give it a try once”, or “why DSL approach and not the other one”, and this time we could notice that portion of people already knew Wasp from before (some even used it), and had more specific questions, even proposing next features that we planned but haven’t published yet.

Beta feedback

Although the core message (DSL for developing full-stack web apps with React & Node.js) hasn’t changed, there was significantly less pushback to the concept than before. I guess it comes down to the time elapsed and the product being more polished and validated from the outside - Beta, published use-cases, testimonials, …

Before the launch​

This was our initial plan:

Launch timeline

For 20 days before the launch we were posting daily countdown banners on Twitter + a few polls (e.g. what's your favourite CSS framework) to engage the audience.

Examples of pre-launch tweets

Our Twitter game is still super young (~500 followers) so it didn't have a big effect but it helped to get the team excited and a few people also noticed it and commented/voted.

Due to the lack of time we ended up doing user testing in-house. That's still something I'd like to improve and make a habit of in the future.

A few other things we did prior to the launch:

  • Redesigned our project page - gave it a new, sleeker look
  • Published use cases with our most successful users and featured them on the project page
  • Activated our Discord and email list
  • Organized a launch event (call on Discord) to celebrate the launch - it went better than expected, a decent amount of people showed up and we had some good discussions!

The launch​

As mentioned, we went with a launch week format - we liked the idea of having a whole week filled with content rather than cramming everything in a single day. We highlighted a new feature every day + launched a hackathon on the last day of the week, to keep the momentum. You can see the full schedule here.

Launch week schedule

We also shared our launch news at different places, most successful being Product Hunt, HackerNews and Reddit.

Product Hunt - failed, but ok​

The mistake we did was launching on the Thanksgiving weekend - there was little (real) traffic + the mods were away so the bots took over!

We ended up as #5 product of the day with ~250 upvotes, which wasn’t so bad because in the end we got featured in their daily newsletter with 1M+ subscribers.

The bad part was that mods were away and pretty much all other products in front of us were fake or obviously bot powered! It felt like there was no real interaction on any of these products, just endless “congrats on the launch” comments from the newly created accounts with obviously fake names. Two products were also clearly violating PH rules (one was the same product that launched a week or two ago, but just changed the name).

The most disappointing part for us (and especially for the team) was that it felt like there aren’t any real people on PH, just bots.

🕹 Post-launch: Wasp Hackathon #1 - Betathon!​

Since we introduced all the new features during the launch week, we thought a good way to keep the community engaged and give them a reason to try Wasp Beta out would be to throw a hackathon! It was the first time we did so we weren't sure how it'd go, but it went better than expected!

Tweet about Betathon - our #1 hackathon!

In the end, it was definitely worth it (see review and submissions here). It was quite lightweight to organize (we even made a custom web app with Wasp for the hackathon which you can also use for your hackathon) and we got some really nice submissions and community shout-outs.

Announcing a launch date publicly is great for productivity​

Another big benefit we noticed from this type of launching is how much more productive it made the whole team. Although the launch date was totally self-imposed (and we did move it a couple of times internally), it was still an amazing forcing function once we announced it publicly. It focused the efforts of the whole team and it also felt great.

We decided to keep going with the quarterly release schedule in this format - 3 months is just enough time to make a dent on the product side, but not long enough to get stuck or caught up with endless refactoring. It also forces us to plan for the features that will have most impact on the developers using Wasp and make their lives easier, because we all want to have something cool and useful to present during the launch week.

Conclusion​

I hope you found this post helpful or at least interesting! Creating a new web framework might be one of the most notorious things to do as a developer, but that shouldn't be a reason not to do it - where are the new frameworks going to come from otherwise?

Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Convincing developers to try a new web framework - the effects of launching beta

· 7 min read
Matija Sosic

Alpha feedback

We are developing an OSS web framework in a form of a config language (DSL) that works with React & Node.js. Getting developers to use a new tool (especially a web framework) is a pretty hard thing to do. We wished there were more stories of how today's mainstream tools got adopted that we could learn from, so that motivated us to document our own.

Want to stay in the loop? → Join our newsletter!

TL;DR​

  • HackerNews launch post brought the most traffic, by far
  • Product Hunt launch went worse than expected, bots took over
  • Our goal was to reach GitHub Trending but we failed
  • Less overall traffic than for the Alpha launch, but much higher quality of feedback + a shift in public perception
  • Having a public launch date made us 3x more productive

📊 The results: stats​

We launched Beta on Nov 27, 2022 in a launch week format, recently popularized by Supabase. During the first week we launched on Product Hunt, and after the weekend we posted on HackerNews. Here's what the numbers were on the last day of the launch:

  • 190 GitHub stars added to the repo
  • 108 new projects started
  • 83 new users (installed Wasp locally and ran it)

Web visitors during beta launch week

HN launch caused almost 2x spike in traffic and usage. Also, although our launch week already ended by the start of December, we actually had the most users ever throughout December:

WAU displayed monthly

Looking back, this wasn't at all our biggest event in terms of traffic, but it was in terms of usage:

All time stats

One of the main effects of the launch (together with a few recent successful HN posts, and the Alpha Testing Program we ran in Jul '22) is that we managed to move the baseline WAU from ~10 to ~20. Another effect, felt more subjectively, is the change in the community perception.

Community perception shift​

As mentioned above, although our Alpha launch had higher absolute numbers (website traffic, HN upvotes etc), it felt that Beta launch caused the biggest perception shift in the community so far.

Before were mostly getting superficial comments like “this looks cool, I’ll give it a try once”, or “why DSL approach and not the other one”, and this time we could notice that portion of people already knew Wasp from before (some even used it), and had more specific questions, even proposing next features that we planned but haven’t published yet.

Beta feedback

Although the core message (DSL for developing full-stack web apps with React & Node.js) hasn’t changed, there was significantly less pushback to the concept than before. I guess it comes down to the time elapsed and the product being more polished and validated from the outside - Beta, published use-cases, testimonials, …

Before the launch​

This was our initial plan:

Launch timeline

For 20 days before the launch we were posting daily countdown banners on Twitter + a few polls (e.g. what's your favourite CSS framework) to engage the audience.

Examples of pre-launch tweets

Our Twitter game is still super young (~500 followers) so it didn't have a big effect but it helped to get the team excited and a few people also noticed it and commented/voted.

Due to the lack of time we ended up doing user testing in-house. That's still something I'd like to improve and make a habit of in the future.

A few other things we did prior to the launch:

  • Redesigned our project page - gave it a new, sleeker look
  • Published use cases with our most successful users and featured them on the project page
  • Activated our Discord and email list
  • Organized a launch event (call on Discord) to celebrate the launch - it went better than expected, a decent amount of people showed up and we had some good discussions!

The launch​

As mentioned, we went with a launch week format - we liked the idea of having a whole week filled with content rather than cramming everything in a single day. We highlighted a new feature every day + launched a hackathon on the last day of the week, to keep the momentum. You can see the full schedule here.

Launch week schedule

We also shared our launch news at different places, most successful being Product Hunt, HackerNews and Reddit.

Product Hunt - failed, but ok​

The mistake we did was launching on the Thanksgiving weekend - there was little (real) traffic + the mods were away so the bots took over!

We ended up as #5 product of the day with ~250 upvotes, which wasn’t so bad because in the end we got featured in their daily newsletter with 1M+ subscribers.

The bad part was that mods were away and pretty much all other products in front of us were fake or obviously bot powered! It felt like there was no real interaction on any of these products, just endless “congrats on the launch” comments from the newly created accounts with obviously fake names. Two products were also clearly violating PH rules (one was the same product that launched a week or two ago, but just changed the name).

The most disappointing part for us (and especially for the team) was that it felt like there aren’t any real people on PH, just bots.

🕹 Post-launch: Wasp Hackathon #1 - Betathon!​

Since we introduced all the new features during the launch week, we thought a good way to keep the community engaged and give them a reason to try Wasp Beta out would be to throw a hackathon! It was the first time we did so we weren't sure how it'd go, but it went better than expected!

Tweet about Betathon - our #1 hackathon!

In the end, it was definitely worth it (see review and submissions here). It was quite lightweight to organize (we even made a custom web app with Wasp for the hackathon which you can also use for your hackathon) and we got some really nice submissions and community shout-outs.

Announcing a launch date publicly is great for productivity​

Another big benefit we noticed from this type of launching is how much more productive it made the whole team. Although the launch date was totally self-imposed (and we did move it a couple of times internally), it was still an amazing forcing function once we announced it publicly. It focused the efforts of the whole team and it also felt great.

We decided to keep going with the quarterly release schedule in this format - 3 months is just enough time to make a dent on the product side, but not long enough to get stuck or caught up with endless refactoring. It also forces us to plan for the features that will have most impact on the developers using Wasp and make their lives easier, because we all want to have something cool and useful to present during the launch week.

Conclusion​

I hope you found this post helpful or at least interesting! Creating a new web framework might be one of the most notorious things to do as a developer, but that shouldn't be a reason not to do it - where are the new frameworks going to come from otherwise?

Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/02/02/no-best-framework.html b/blog/2023/02/02/no-best-framework.html index 28a4f07da6..01c9a78393 100644 --- a/blog/2023/02/02/no-best-framework.html +++ b/blog/2023/02/02/no-best-framework.html @@ -19,13 +19,13 @@ - - + + -
-

The Best Web App Framework Doesn't Exist

· 3 min read
Vinny

The web app framework you choose doesn’t really matter. Well, it matters, just not as much as others would like you to believe.

The fact that so many libraries and frameworks exist in 2023, and that the best one is still hotly debated, proves my point. It’s the web developers biggest “first-world problem” — a problem that’s not really a problem. On Maslow’s Hierarchy of Developer Needs, it’s definitely near the top (ok, I made that up 😅)


hierarchy of developer needs


For example, according the the StateOfJS survey, there were 5 Front-end Frameworks with good retention in 2018, now there are 11 in 2022. That’s a 120% increase in a matter of 4 years, and that’s not even taking into account the hot meta-frameworks like NextJS, SvelteKit, or Astro!


State of JS 2022
A growing family of frameworks...


These are great developments for the space, overall. They improve things like developer speed, bundle size, performance, and developer experience. But they also make it damn hard for developers and teams to make a decision when trying to decide which to use for their next project. It’s even worse for beginners, which is probably why they just go for React — which, of course, is perfectly fine.

And I think all of this is OK, because in the end it doesn’t really matter which one you choose. When it really comes down to it, all that matters is that the framework you chose:

  • Is stable
  • Allows you to move quickly
  • Allows you to reach your end goal

Why? Because most of them are built around the same concepts, have proven themselves capable of performing at scale, and have communities you can engage with and learn from.

React might be the most prominent in job descriptions, but if you’re looking for a new role and only have experience in Vue or Angular, I can’t imagine it would take you more than a week to build a side-project with React to display your ability to prospective employers.

On the flip side, if you’re a beginner or Junior dev, once you have the basics of HTML, CSS, and JS under your belt, it doesn’t really matter what framework you learn. I personally started learning backend development with Node/ExpressJS, but landed my first role as a Frontend developer with Angular. In my second role I used NextJS, and now I work with Wasp (a full-stack framework built on top of React and ExpressJS). Developers never stop learning, so it’s kind of a non-argument to deride any specific framework — unless it really sucks, but then no one will continue to use it anyway.


Use what works


So, in the end, use what works. Because in 99.99% of cases, your choice of web framework will not decide the fate of your project.

If you’ve done a bit of research and found a framework that suits your needs and you enjoy using it — use it. There’s really no good reason not to.


Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

The Best Web App Framework Doesn't Exist

· 3 min read
Vinny

The web app framework you choose doesn’t really matter. Well, it matters, just not as much as others would like you to believe.

The fact that so many libraries and frameworks exist in 2023, and that the best one is still hotly debated, proves my point. It’s the web developers biggest “first-world problem” — a problem that’s not really a problem. On Maslow’s Hierarchy of Developer Needs, it’s definitely near the top (ok, I made that up 😅)


hierarchy of developer needs


For example, according the the StateOfJS survey, there were 5 Front-end Frameworks with good retention in 2018, now there are 11 in 2022. That’s a 120% increase in a matter of 4 years, and that’s not even taking into account the hot meta-frameworks like NextJS, SvelteKit, or Astro!


State of JS 2022
A growing family of frameworks...


These are great developments for the space, overall. They improve things like developer speed, bundle size, performance, and developer experience. But they also make it damn hard for developers and teams to make a decision when trying to decide which to use for their next project. It’s even worse for beginners, which is probably why they just go for React — which, of course, is perfectly fine.

And I think all of this is OK, because in the end it doesn’t really matter which one you choose. When it really comes down to it, all that matters is that the framework you chose:

  • Is stable
  • Allows you to move quickly
  • Allows you to reach your end goal

Why? Because most of them are built around the same concepts, have proven themselves capable of performing at scale, and have communities you can engage with and learn from.

React might be the most prominent in job descriptions, but if you’re looking for a new role and only have experience in Vue or Angular, I can’t imagine it would take you more than a week to build a side-project with React to display your ability to prospective employers.

On the flip side, if you’re a beginner or Junior dev, once you have the basics of HTML, CSS, and JS under your belt, it doesn’t really matter what framework you learn. I personally started learning backend development with Node/ExpressJS, but landed my first role as a Frontend developer with Angular. In my second role I used NextJS, and now I work with Wasp (a full-stack framework built on top of React and ExpressJS). Developers never stop learning, so it’s kind of a non-argument to deride any specific framework — unless it really sucks, but then no one will continue to use it anyway.


Use what works


So, in the end, use what works. Because in 99.99% of cases, your choice of web framework will not decide the fate of your project.

If you’ve done a bit of research and found a framework that suits your needs and you enjoy using it — use it. There’s really no good reason not to.


Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/02/14/amicus-indiehacker-interview.html b/blog/2023/02/14/amicus-indiehacker-interview.html index 67f83967cb..cb5ddf2c07 100644 --- a/blog/2023/02/14/amicus-indiehacker-interview.html +++ b/blog/2023/02/14/amicus-indiehacker-interview.html @@ -19,14 +19,14 @@ - - + + -
-

From Idea to Paying Customers in 1 Week: An Interview with Amicus.work

· 8 min read
Vinny

I guess it was less me having an idea and validating it, and more a valid idea coming to me and biting me in the ass, and me thinking ‘oh hey…’ +

+

From Idea to Paying Customers in 1 Week: An Interview with Amicus.work

· 8 min read
Vinny

I guess it was less me having an idea and validating it, and more a valid idea coming to me and biting me in the ass, and me thinking ‘oh hey…’   — Erlis Kllogjri


Erlis Kllogjri, a computer engineer and the creator of Amicus.work, went from idea to paying customers in just one week 🤯! In this interview, he tells how sometimes the best ideas come looking for you, and how moving quickly can help you stay inspired, motivated, and pull in your first satisfied customers.


Amicus Homepage

Before we begin with the unlikely origin story of Amicus.work, can you tell us a bit about what it is?​

Amicus is a SaaS tool for legal teams that helps keep you organized and on top of your legal needs. Think of it like "Asana for lawyers", but with features and workflows tailored to the domain of law.

It allows attorneys and their clients to easily track the progress of the legal case they are dealing with, and collaborate with others involved in the case, all in one central location. For example, deadline reminders help with not missing key dates and workflow visualization allows lawyer and client to see where the process is stuck, and get it unstuck.

Your time from initial idea to working MVP seemed fast. How long was it and how did you achieve it so quickly?​

From the initial discussions to the launch of the initial prototype was probably a week or so. This is even quicker than it sounds because I was working a full time job at the time. The speed [of execution] was fully enabled by Wasp, a full-stack web app framework.

I was looking at other solutions, but none of them were full-stack and sounded like a lot of work just to stitch everything together and get started. I just wanted to get the job done and didn’t care about picking the stack specifics myself. Wasp was really helpful as it set me up with the best practices and I had everything running in just a few minutes!

How were you able to get these first customers so quickly?​

The first user is a little bit of a cheat because I know them — my brother, who is a lawyer. But having read about other entrepreneurs, this is not that uncommon. Sometimes the first users we know are ourselves, sometimes they’re family or friends, and sometimes it’s someone you sought out. But I think it was important to have the client before the idea, because that way you have the problem before the solution.

What advice would you give to other Solopreneurs regarding the validation process?​

With regard to process, I spent a lot of time having discussions with my first user - my brother. The better you know the first user, the more careful you need to be I think. They’re going to give you slack and support your ideas. You don’t really want that, so you have to dive deeper into each problem/solution - like asking 5 why’s, so you can be more objective.

Once more users came on, I began sending out surveys about the key things I wanted to know. I also started setting up SQL queries and adding logs to answer questions about what kind of user was using what features the most etc. Being a solopreneur means you have to be even more careful about what you spend your time building.

MRR is low at the moment, around ~$90, and the first goal is to get to an MRR around ~$2,000. At that point I would be able to throw more time and resources at the application, increase the utility, and kick off a virtuous cycle of more revenue and utility.

That’s great. So rather than trying to find a clever idea, the idea found you.​

It’s funny because I have all of these harebrained ideas that I’m always kicking around, thinking about how to validate them: MVPs, setting up a landing page that gets emails or deposits, etc.

Meanwhile my brother was telling me about this pain of managing matters that no tool really helped with. Clients want to know where the process is, how many steps are left, how they need to be reminded of important dates like contract deadlines, etc. So I agreed to build something to see if it would help. Wasp was instrumental here because if these steps had taken too long I would have probably lost interest and gotten distracted by something else. It allowed me to abstract all the details of a full stack app and focus on the product itself.

I built the prototype and it was TERRIBLE, it hurts to think back on that first version. But it was being used, and terrible though it was, it was still providing utility. And that was the point where it clicked the idea would work - if my first crude attempt was useful, and it would only get better with each iteration, there is a space here to provide so much value that some of it can be captured.

I guess it was less me having an idea and validating it, and more a valid idea coming to me and biting me in the ass, and me thinking ‘oh hey…’.

What’s been the biggest lessons learned as a result from building Amicus? If you could do it over, what would you do the same and what would you do differently?​

I think one of the things I would do differently is spend a little more time at the beginning getting a full grasp on the use cases. I tried doing this with interviews with the first client. However once what was intended was built, I come across all of these questions that weren’t initially obvious. I have seen PMs in the past create paper mockups (or using Figma if there is time) and walking a person through what they would do - then all of a sudden these assumptions you both had bubble up. [I] would probably do something like that if possible.

What were your biggest concerns before getting started building Amicus? What problems did you know you wanted to avoid and how did you successfully achieve those goals?​

[My] biggest concern when getting started building Amicus was honestly that it would go to the unfinished project graveyard. Once again, Wasp was key to resolving this. Being able to remove most of the redundancy involved in making a full stack app really helped me. It allowed me to focus on the interesting problems.

One of the things I have been trying to be careful to avoid is building things that aren’t needed or solving problems that don’t exist. It is very easy to get into the trap of thinking ‘oh this would be cool’ or ‘oh this extra thing might need to be build incase…’. I have been trying to be rigorous about validating features before building them (by talking to users or through the surveys), and unless theres a good reason to believe something is a problem I don’t spend my time fixing it. This is very hard, but it has allowed me to focus.


Wasp Logo

Have you done any form of advertising? press releases? How are you spreading the word about Amicus at the moment?​

No advertising yet and no press releases either. Right now spreading of the word is mostly through word of mouth. Advertising can be a money pit, especially when you don’t know what you’re doing (and I probably don’t know what I am doing) so I want to first make sure I am at the point where users feel passionate enough about Amicus to where they tell others about it. Once I get there, advertising can have a bigger return even with my fumbling.

What made you decide to go it alone as a “Solopreneur”? Were you confident that you’d be able to tackle the challenge alone, and if so why?​

This wasn’t so much a decision as something that came about one decision at a time. What initially started as just a handy app for my brother to use, naturally grew in scope and utility, and all of a sudden there was a business and I effectively became a solopreneur. Although I’ve always wanted to be an entrepreneur, I didn’t realize I had become a solopreneur until after the fact.

Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2023/02/21/junior-developer-misconceptions.html b/blog/2023/02/21/junior-developer-misconceptions.html index b95449a40a..83b878fc31 100644 --- a/blog/2023/02/21/junior-developer-misconceptions.html +++ b/blog/2023/02/21/junior-developer-misconceptions.html @@ -19,15 +19,15 @@ - - + + -
-

The Most Common Misconceptions Amongst Junior Developers

· 6 min read
Vinny

High code quality only indirectly affects users. The main purpose is to keep development velocity high which benefits all stakeholders +

+

The Most Common Misconceptions Amongst Junior Developers

· 6 min read
Vinny

High code quality only indirectly affects users. The main purpose is to keep development velocity high which benefits all stakeholders   — zoechi


We recently asked the web dev community on Reddit.com what the most common misconceptions are amongst junior developers, and we got a ton of great responses -- more than 270 to be exact.

Because there was so much to discuss, Matija and I decided to summarize the replies and give our own opinions in a longer-form YouTube video, which you can watch below.

You can also continue reading further for a summary of the main concepts.

The Most Common Themes​

Among the responses were lots of great, specific examples, but we noticed a lot of common themes within them:

  • Code Quality
  • Managing Time & Expectations
  • Effective Communication & Teamwork

These seemed to be the topics senior devs had the most to say about. And it makes sense -- these are the things that, when you get to the core of the issues, can make or break almost any career.

It was also interesting to see that the top replies were issues that encompassed all of these themes. For example, take the top-voted reply:

Clean it up later
The most common misconception is that you're going to come back and clean that up later.

First Quality & Then Velocity​

The top reply above touches on all three of the common themes we outlined, because within it is a message about quality -- about doing things correctly. And whenever you speak about quality, there is an inherent assumption that it takes longer, so we're also talking about time management. And, if you're a part of a team, you can't work effectively without good communication and teamwork.

Nevertheless, in the "quality" debate there were effectively two camps, with those who thought quality code was about:

  1. writing clean, readable code, that's easy to maintain
  2. writing code that gets shipped on time and works.

The balance between meeting deadlines, shipping features, and writing the best possible code is obviously a tricky one to get right. Some people had the opinion that business realities trump clean code patterns in the dash to meet deadlines and keep clients happy, while others thought that clean, quality code should be the priority, and that by making it a priority you can actually increase long-term velocity, even if short-term deadlines aren't met.

You don't have to touch all the code you see

This discussion can distract from Junior developers priorities though, which are to grow and improve as a developer, not lead the team to success. Therefore, it's probably best for Junior devs to focus on quality first, and then improve their speed of delivery second.

Stay Humble & Manage Expectations​

As a Junior developer, it's not expected that you're going to get everything right the first time. There is an assumption that you will learn the best practices over time, and along the way you might produce inconsistent work, make mistakes, or even possibly break some things along the way.

But that's okay.

It's part of the process. It's expected. And it's important to remember that this is not a reflection of your value or worth as an engineer or individual.

In the replies, there were also many developers who recognized another developer's desire "to fix things later" as a way to brush off criticism towards their work. They generally viewed this as a bad habit to get into, as it is often one that plagues developers even as they gain more experience. "Code reviews are not personal", and being able to take criticism graciously is an important skill to develop. After all, seniors are there to guide you towards making better decisions based on their own experiences. And juniors are there to learn.

The senior dev doesn't know everything

But how often should you seek a Senior's advice? Should you do what they said, or what some dude told you is the only way to do x on YouTube or in some blogpost ;) ?

Should you ask for help every time you get stuck, or should you compromise your sanity and struggle alone for days?

Well, it depends on who you ask. But most of the replies made it clear that:

  1. You should try it out yourself first.
  2. Use the resources available to you (Google, Stack Overflow, GPT) to try and figure it out.
  3. Ask for help once you considerably slow down on making any progress.
  4. If you have a possible solution and it differs from the senior dev's suggestion, that doesn't mean it's wrong -- there can sometimes be many possible ways to achieve the same goal!

Bothering seniors with questions

Be Flexibile & Open to Change​

Nothing changes faster than the world of technology. As a developer, you need to constantly be learning and adapting to new technologies and trends. If you don't like change, well then being a software developer probably isn't the right career for you.

Everything takes longer than you think

On top of things changing constantly, it's the kind of job that challenges your assumptions. What you think might be the best solution turns out to be incompatible with your team's desired goals or end product, and you're forced to use a "sub-optimal" solution instead. Why? Because it's the best way to get the job done given your team's constraints. "Sorry, pal, but we can't use your favorite framework on this one."

The developers who stay flexible and open-minded are often at an advantage here. They're the ones that are less dogmatic about a particular technology or approach, and are more willing to adapt to the situation at hand. They're typically the ones that progress faster than their peers, and they're the ones that get the job done well.

Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2023/03/02/wasp-beta-update-feb.html b/blog/2023/03/02/wasp-beta-update-feb.html index 82a1771857..e686b69bc5 100644 --- a/blog/2023/03/02/wasp-beta-update-feb.html +++ b/blog/2023/03/02/wasp-beta-update-feb.html @@ -19,14 +19,14 @@ - - + + -
-

Wasp Beta - February 2023

· 6 min read
Matija Sosic

Wasp Update Feb 23

Want to stay in the loop? → Join our newsletter!

Hey Wasp acolytes (Waspolytes?) 🐝,

What's kickin'? We at Wasp spent the whole month thinking of the coolest features to add to our next release and we can't wait to share it with you!

Tell me now
Ok ok, we're getting there, chill!

Let me cut to the chase and show you what's been cooking in Wasp pot for the past month:

Deploy to Fly.io with a single command for free 🚀☁️​

Deploy to fly.io with single command

This is the only command you need to run to deploy your full app (client, server, and database) to Fly.io! They also offer a generous free tier so you can deploy your v1 without any second thoughts.

Check out our docs for more details: Deploying your Wasp app to Fly.io

✅ Full stack TypeScript support​

Types everywhere

This is one of the features we are most excited about! Now, when you define an entity in your Wasp file, it immediately becomes accessible as a type both on a client and a server.

Full stack TypeScript support

This feature beautifully showcases the power of the Wasp language approach and how much it can cut down on the boilerplate. And we're just getting started!

For more details, check out our entity docs.

🗓 We set a date for the next launch - April 11th! 🚀​

Launch party

Mark your calendars, it's official! We will release the next version of Wasp on April 11th - in exactly 40 days! As the last time, we will follow a launch week format with a lot of memes, swag and fun prizes (Including Da Boi, of course).

Here's a quick list of the planned features:

  • Using Vite instead of CRA under the hood - you'll be able to create new Wasp apps in a blink of an eye! 🚀
  • Custom API routes
  • Code scaffolding for the quicker start
  • Support for sending emails
  • Password reset via email
  • Improved Auth UI
  • Testing support

And more! This is quite an ambitious plan but we are fully committed to getting it done. Any comments or ideas, ping us on our Discord.

☎️ We had our Community Call #2 - meet Da Boi​

We had a community call

We had so much fun on our last community call that we decided we have to do it again! As you can notice, our community-approved mascot Da Boi stole the show. The rest was pretty much just a filler and an excuse to have more fun with Da Boi :D.

On a serious note, it was great to catch up with the community prior to the next release - we discussed features and the roadmap and everybody shared what they're building and what they'd like to see next in Wasp.

🎥 Wasp is now on YouTube!​

Wasp is on YouTube

We are still going strong with our YouTube! The latest video started as a question on Reddit and it escalated quite quickly, with 200+ comments - we cover the responses we received + our expert commentary :D.

If you want to stay in the loop (and I guess you do since you're reading this :D), please subscribe to our channel and help us reach the first 100 subscribers on YouTube!

Subscribe to Wasp on YouTube
You know you want it!

⌨️ From the blog​

🕹 Community highlights​

  • PhraseTutor: Learn Italian in a week! There is a new app built from scratch with Wasp, by Mihovil - one of our early community members who recently joined the team as an engineer! It's smooth both on the front end and back end and will teach you Italian before you can say (or eat) "quattro formaggi"!

    Phrase Tutor

Developer life 💻⌨️💽​

Here is the cool stuff we came across this month

Wasp Github Star Growth - 2,317 ⭐️, woohoo!​

Huge thanks to all our contributors and stargazers - you are amazing!

Wasp has over 2,000 GitHub stars

And if you haven't yet, please star us on Github! Yes, we are shameless star beggars, but if you believe in the project and want to support it that's one of the best ways to do it (next to actually building something with Wasp - go do that too! :D)

That's a wrap! Thanks for reading and we can't wait for our next launch to get out and see how you like it. As always, we're on Discord and appreciate any comments, feedback, and ideas - that's how Wasp came to be!

As a parting gift, here are a few curated Da Boi memes created by our valued community members:

Wasp's new mascot

Buzzy buzz, you got that snazz 🐝 🐝,
+

+

Wasp Beta - February 2023

· 6 min read
Matija Sosic

Wasp Update Feb 23

Want to stay in the loop? → Join our newsletter!

Hey Wasp acolytes (Waspolytes?) 🐝,

What's kickin'? We at Wasp spent the whole month thinking of the coolest features to add to our next release and we can't wait to share it with you!

Tell me now
Ok ok, we're getting there, chill!

Let me cut to the chase and show you what's been cooking in Wasp pot for the past month:

Deploy to Fly.io with a single command for free 🚀☁️​

Deploy to fly.io with single command

This is the only command you need to run to deploy your full app (client, server, and database) to Fly.io! They also offer a generous free tier so you can deploy your v1 without any second thoughts.

Check out our docs for more details: Deploying your Wasp app to Fly.io

✅ Full stack TypeScript support​

Types everywhere

This is one of the features we are most excited about! Now, when you define an entity in your Wasp file, it immediately becomes accessible as a type both on a client and a server.

Full stack TypeScript support

This feature beautifully showcases the power of the Wasp language approach and how much it can cut down on the boilerplate. And we're just getting started!

For more details, check out our entity docs.

🗓 We set a date for the next launch - April 11th! 🚀​

Launch party

Mark your calendars, it's official! We will release the next version of Wasp on April 11th - in exactly 40 days! As the last time, we will follow a launch week format with a lot of memes, swag and fun prizes (Including Da Boi, of course).

Here's a quick list of the planned features:

  • Using Vite instead of CRA under the hood - you'll be able to create new Wasp apps in a blink of an eye! 🚀
  • Custom API routes
  • Code scaffolding for the quicker start
  • Support for sending emails
  • Password reset via email
  • Improved Auth UI
  • Testing support

And more! This is quite an ambitious plan but we are fully committed to getting it done. Any comments or ideas, ping us on our Discord.

☎️ We had our Community Call #2 - meet Da Boi​

We had a community call

We had so much fun on our last community call that we decided we have to do it again! As you can notice, our community-approved mascot Da Boi stole the show. The rest was pretty much just a filler and an excuse to have more fun with Da Boi :D.

On a serious note, it was great to catch up with the community prior to the next release - we discussed features and the roadmap and everybody shared what they're building and what they'd like to see next in Wasp.

🎥 Wasp is now on YouTube!​

Wasp is on YouTube

We are still going strong with our YouTube! The latest video started as a question on Reddit and it escalated quite quickly, with 200+ comments - we cover the responses we received + our expert commentary :D.

If you want to stay in the loop (and I guess you do since you're reading this :D), please subscribe to our channel and help us reach the first 100 subscribers on YouTube!

Subscribe to Wasp on YouTube
You know you want it!

⌨️ From the blog​

🕹 Community highlights​

  • PhraseTutor: Learn Italian in a week! There is a new app built from scratch with Wasp, by Mihovil - one of our early community members who recently joined the team as an engineer! It's smooth both on the front end and back end and will teach you Italian before you can say (or eat) "quattro formaggi"!

    Phrase Tutor

Developer life 💻⌨️💽​

Here is the cool stuff we came across this month

Wasp Github Star Growth - 2,317 ⭐️, woohoo!​

Huge thanks to all our contributors and stargazers - you are amazing!

Wasp has over 2,000 GitHub stars

And if you haven't yet, please star us on Github! Yes, we are shameless star beggars, but if you believe in the project and want to support it that's one of the best ways to do it (next to actually building something with Wasp - go do that too! :D)

That's a wrap! Thanks for reading and we can't wait for our next launch to get out and see how you like it. As always, we're on Discord and appreciate any comments, feedback, and ideas - that's how Wasp came to be!

As a parting gift, here are a few curated Da Boi memes created by our valued community members:

Wasp's new mascot

Buzzy buzz, you got that snazz 🐝 🐝,
Matija, Martin and the Wasp team

Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2023/03/03/ten-hard-truths-junior-developers-need-to-hear.html b/blog/2023/03/03/ten-hard-truths-junior-developers-need-to-hear.html index ae63a9885d..c07bccfda3 100644 --- a/blog/2023/03/03/ten-hard-truths-junior-developers-need-to-hear.html +++ b/blog/2023/03/03/ten-hard-truths-junior-developers-need-to-hear.html @@ -19,13 +19,13 @@ - - + + -
-

10 "Hard Truths" All Junior Developers Need to Hear

· 4 min read
Vinny

hard truths for junior devs

Ok, I have to admit, these aren’t really Truths, but rather some opinions I’ve formed over my journey switching careers from Educator to Developer.

It’s well known at this point that software — especially web — development is a viable option for someone looking for a new career without going the traditional education route. Due to this, and the fact that salaries tend to be very good, I think a portion of people making the switch might be doing it for the wrong reasons.

And once you get into that career, as a Junior it can often be difficult to know what you should be doing to advance your career. There are a ton of opinions out there (including mine) and juniors tend to develop a lot of misconceptions, as my colleague and I discussed in our recent Reddit post and follow-up video.

So, I put together this list of things you should consider when starting out a career in tech:

  1. 👎 If you’re doing it solely for the money, you’re not gonna make it. True, you don’t need a degree or anyone’s permission to advance in this career, but you need ambition and mental stamina. A genuine interest is needed to maintain them.

  2. 😎 You don’t have to follow the trends. Follow what interests you. Like I said before, you need mental stamina in this field of work. Following your interests will keep you engaged and help avoid burnout.

  3. 👩‍💻 You don’t need to know a piece of tech inside and out, contrary to what some devs might want you to believe. The truth is, you are always learning, and there will always be gaps in your knowledge. Your confidence in being able to fill those gaps is what matters.

  4. 🧱 Start building, ASAP. Find a problem that interests you and build the solution yourself. Contribute to Open-Source projects that you use. A portfolio of unique work speaks volumes about your abilities. Plus, there’s no better teacher than experience.

  5. 😱 Be fearless and seek feedback. Put your work out there and be ready to have it criticized. If you can stomach it, you’ll come out the other side a much better developer.

  6. 🧐 You should have a firm understanding of what you’re doing. Don’t copy-paste someone else’s answer (or GPT’s) to your problem and call it a day. Question why things work, and figure it out for yourself.

  7. 🏋️‍♀️ You have to do the grunt work, unfortunately. Don’t expect high salaries from the beginning. And you’ll probably want to improve your portfolio by working on side projects in your free time, or you might stay a junior dev for longer than you wish.

  8. 🧗‍♂️ Challenge yourself. Don’t let yourself get too comfortable. If you do, you won’t improve. Offer to take new, difficult, and daunting tasks at work or with your personal projects. You’ll be surprised what you can achieve.

  9. 💰 You don’t have to pay for boot camps or courses. In fact, you’re better off tackling problems on your own and only asking for help if you’re truly stuck. There’s a wealth of free resources out there, and when you’re on the job, these might be the only things to assist you.

  10. 🗣 Programming is definitely not the only skill you’ll need. Being respectful, communicative, conscientious, ambitious, and humble will put you in a different league and make you a valuable asset in any tech team.

TIP: Looking for some inspiration? Feedback? Motivation? Join us over at the Wasp Discord server, where we've got an active, friendly community of web developers of all skill levels that build side-projects, share their experiences, make memes, and chat about life


Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

10 "Hard Truths" All Junior Developers Need to Hear

· 4 min read
Vinny

hard truths for junior devs

Ok, I have to admit, these aren’t really Truths, but rather some opinions I’ve formed over my journey switching careers from Educator to Developer.

It’s well known at this point that software — especially web — development is a viable option for someone looking for a new career without going the traditional education route. Due to this, and the fact that salaries tend to be very good, I think a portion of people making the switch might be doing it for the wrong reasons.

And once you get into that career, as a Junior it can often be difficult to know what you should be doing to advance your career. There are a ton of opinions out there (including mine) and juniors tend to develop a lot of misconceptions, as my colleague and I discussed in our recent Reddit post and follow-up video.

So, I put together this list of things you should consider when starting out a career in tech:

  1. 👎 If you’re doing it solely for the money, you’re not gonna make it. True, you don’t need a degree or anyone’s permission to advance in this career, but you need ambition and mental stamina. A genuine interest is needed to maintain them.

  2. 😎 You don’t have to follow the trends. Follow what interests you. Like I said before, you need mental stamina in this field of work. Following your interests will keep you engaged and help avoid burnout.

  3. 👩‍💻 You don’t need to know a piece of tech inside and out, contrary to what some devs might want you to believe. The truth is, you are always learning, and there will always be gaps in your knowledge. Your confidence in being able to fill those gaps is what matters.

  4. 🧱 Start building, ASAP. Find a problem that interests you and build the solution yourself. Contribute to Open-Source projects that you use. A portfolio of unique work speaks volumes about your abilities. Plus, there’s no better teacher than experience.

  5. 😱 Be fearless and seek feedback. Put your work out there and be ready to have it criticized. If you can stomach it, you’ll come out the other side a much better developer.

  6. 🧐 You should have a firm understanding of what you’re doing. Don’t copy-paste someone else’s answer (or GPT’s) to your problem and call it a day. Question why things work, and figure it out for yourself.

  7. 🏋️‍♀️ You have to do the grunt work, unfortunately. Don’t expect high salaries from the beginning. And you’ll probably want to improve your portfolio by working on side projects in your free time, or you might stay a junior dev for longer than you wish.

  8. 🧗‍♂️ Challenge yourself. Don’t let yourself get too comfortable. If you do, you won’t improve. Offer to take new, difficult, and daunting tasks at work or with your personal projects. You’ll be surprised what you can achieve.

  9. 💰 You don’t have to pay for boot camps or courses. In fact, you’re better off tackling problems on your own and only asking for help if you’re truly stuck. There’s a wealth of free resources out there, and when you’re on the job, these might be the only things to assist you.

  10. 🗣 Programming is definitely not the only skill you’ll need. Being respectful, communicative, conscientious, ambitious, and humble will put you in a different league and make you a valuable asset in any tech team.

TIP: Looking for some inspiration? Feedback? Motivation? Join us over at the Wasp Discord server, where we've got an active, friendly community of web developers of all skill levels that build side-projects, share their experiences, make memes, and chat about life


Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/03/08/building-a-full-stack-app-supabase-vs-wasp.html b/blog/2023/03/08/building-a-full-stack-app-supabase-vs-wasp.html index 1da9c2c5a8..eb0359a862 100644 --- a/blog/2023/03/08/building-a-full-stack-app-supabase-vs-wasp.html +++ b/blog/2023/03/08/building-a-full-stack-app-supabase-vs-wasp.html @@ -19,13 +19,13 @@ - - + + -
-

Building a full-stack app for learning Italian: Supabase vs. Wasp

· 14 min read
Mihovil Ilakovac

wasp vs. supabase

Intro​

What to expect​

In this blog post, I will explain how I created the Phrase Tutor app for learning Italian phrases using two different technologies. I will share some code snippets to show what was required to build the app with both Wasp and Supabase.

Phrase Tutor’s front-end
Phrase Tutor’s front-end

As a senior full-stack developer with experience in building many side-projects, I prefer a quick development cycle. I enjoy turning ideas into POCs in just a few days or even hours.

We will examine how each technology can help when building a full-stack app and where Wasp and Supabase excel.

I wanted to learn Italian fast​

Whenever I travel abroad, I enjoy imagining what it would be like to live in that place. For instance, I usually don't like taking crowded public transportation, but for some reason, it brings me joy when I do it in a foreign country. It's all about the feeling that I'm living there. One of the most important things for me to fully experience the culture is to learn the language or, at the very least, be able to not speak English all the time.

Pretending to be Italian
Pretending to be Italian

My girlfriend and I were planning a trip to Italy, and I wanted to learn some Italian. I thought about what would be the easiest way to learn as much as possible with the least amount of effort. I decided that learning the top 100 Italian phrases would be a good start. I had a week to do it, and learning 100 phrases seemed doable if I practiced every day.

The learning method​

In high school, I had a system for learning historical facts and dates quickly called "focusing on things you don’t know".

Here's how it works:

  1. Gather a pool of facts you want to learn (e.g. "When did WWI start?" - "1914").
  2. Ask yourself each question in the pool.
  3. If you know the answer, remove the fact from the pool.
  4. If you don't know the answer, keep it in the pool.
  5. Repeat with the smaller pool until there are no more facts left.

I made a small app for this and shared it with my classmates, but it didn't go further than that.

Now, I want to use the same method to learn Italian phrases for my trip. So, as a better developer now, I'll make a proper app and host it somewhere 🙂

Building the Phrase Tutor app​

We will create an app that follows the method described above. The app will show you a phrase and you can tell it if you know the translation or not by selecting "I knew it" or "I didn't know it".

How the learning in the app should work
How the learning in the app should work

The app will keep track of your answers and suggest which phrases you should learn next 🕵️

I’ve built the app twice: first with Supabase and then with Wasp. Supabase is a well-rounded open-source Backend as a Service (BaaS) product that adds superpowers to your front-end apps. On the other hand, Wasp is an open-source framework for building full-stack apps that helps to keep the boilerplate low. Let’s see how they compare.

Initial Supabase version​

When I made the initial version, I worked heavily with Vue.js, which I used to create the first version of the Phrase Tutor app. I started by collecting some phrases. I searched on Google for "best Italian phrases to learn" and came across an article titled "100 Italian phrases to learn." (After extracting the phrases from the HTML, I found out that there were only 96 phrases, but that was still good enough for me.)

The initial app contained the phrases in a JSON file that the frontend loaded. It was completely static, but it worked.

{
    "id": 1,
    "group": "general",
    "translations": {
        "en": "Yes",
        "it": "Si"
    }
}

I put it on Cloudflare Pages and it went live.

I showed it to my girlfriend, but she didn't like some of the phrases I used. If only I had a backend with a database to edit the phrases. Then I had an idea: let's add a database with Supabase.

Supabase is a managed backend solution that provides a lot of free stuff: a PostgreSQL database and social authentication among other things.

Phrase Tutor built with Supabase
Phrase Tutor built with Supabase

I set up the database tables using the Supabase UI which was pretty straightforward.

The table I needed only had a few fields:

CREATE TABLE phrases (
    id bigint  NOT NULL,
    group character varying  NULL,
    translations_en text  NOT NULL,
    translations_it text  NOT NULL
);

Then I had to seed the database with some SQL. Executing SQL statements is easy with the use of Supabase’s UI. You just log in, open the SQL editor and paste in the code:

INSERT INTO phrases(id,"group",translations_en,translations_it) VALUES (1,'general','Yes','Si');
INSERT INTO phrases(id,"group",translations_en,translations_it) VALUES (2,'general','No','No');
...

Integrating Supabase into my existing front-end app was simple using their Javascript SDK. If you're familiar with Firebase, it should feel similar. Essentially, you build your SQL queries on the frontend and use the resulting data in your app.

Using the SDK felt pretty straightforward and I could get what I wanted out of the database without much hassle.

const { data, error } = await supabase.from("phrases").select("*");

And just like that, my static Vue.js app had a database to rely on 🎉

Adding the login with Google was a matter of enabling it in Supabase UI and setting up the Client ID and Client Secret variables. In order to trigger the login process with Google, I once again relied on their Javascript SDK.

supabase.auth.signInWithOAuth({ provider: "google" });

Awesome! I'm glad that I can now edit the phrases and that there is a login feature that I plan to use later.

In the future, I have plans to add more languages to the app and also allow registered users to contribute new phrases and translations. I believe this will make the app more useful and engaging for language learners.

And just like that, my app went from a pure static app to an app with a database and Google login 🤯

info

Check out the deployed app written with Vue.js and Supabase: https://phrase-tutor.pages.dev

info

View the source here

Joining Wasp and dogfooding it​

Some background before the second part: I started working at Wasp earlier this year. I'm really happy to work on a technology that solves a problem I care about: when I do side-projects, I dislike writing the same dull parts every time from scratch. I copy and paste from my previous side projects, but eventually, the code snippets become old and outdated.

Naturally, I wanted to test out Wasp by rewriting one of my side projects. I decided to see how Wasp could work with the Phrase Tutor project.

Wasp works by having an easy-to-understand config file called main.wasp which coordinates your pieces of client and server functionalities. Its main purpose is to keep you productive and focused on writing interesting bits. It feels pretty much like using a web framework that covers your whole app.

Phrase Tutor built with Wasp
Phrase Tutor built with Wasp

Let's begin by creating the data models. Wasp uses Prisma under the hood to communicate with your database, which makes it easy to manage your database without worrying about the details. This is just one of the many choices the framework made for me, and I appreciate the feeling of using a setup that works.

I had to first declare all of the entities I needed with Prisma PSL in the Wasp config file.

entity Phrase {=psl
  id Int @id @default(autoincrement())
  group String
  phrase String
  translations Translation[]
psl=}

entity Language {=psl
  id Int @id @default(autoincrement())
  name String @unique
  emoji String
  translations Translation[]
psl=}

entity Translation {=psl
  id Int @id @default(autoincrement())
  phraseId Int
  languageId Int
  translation String
  phrase Phrase @relation(fields: [phraseId], references: [id], onDelete: Cascade)
  language Language @relation(fields: [languageId], references: [id], onDelete: Cascade)
psl=}

I'm using a PostgreSQL database again, and you can see that the field definitions are similar.

I improved the data schema a bit by defining three tables instead of one. I separated the concept of a Phrase from the concepts of Language and Translation. This will make it easier to add new languages in the future.

I added some phrases to the database using Prisma and a Wasp action:

export async function seedItalianPhrases(args, context) {
    const data = [
       {
            id: 1,
            group: "general",
            translations_en: "Yes",
            translations_it: "Si"
        },
        ...
    ]
    for (const phrase of seedPhrases) {
        await context.entities.Phrase.create({
            ...
        });
    }
}

Let’s now look at what I needed to do to get the data flowing from the backend to my React app.

First, I declared a query in my Wasp config file:

app phraseTutor {
  ...
}
...

query fetchAllPhrases {
  fn: import { getAllPhrases } from "@server/queries.js",
  entities: [Phrase]
}

Then I wrote the code for my backend to fetch the phrases. You’ll notice it’s quite similar to the code I wrote for fetching phrases with the Supabase SDK, but I had to include the translations relation since we now have multiple tables.

// My query got the Prisma entity through the context parameter
// which I just used to fetch all the phrases
export async function getAllPhrases(args, context) {
    return context.entities.Phrase.findMany({
        include: {
            translations: true
        }
    });
}

And lastly, I could just import the query into my React app. It’s set up in a way that it handles cache invalidation automatically, one less thing to worry about, which is awesome 😎

// Wasp relies on React Query in the background
const { data: phrases, isLoading } = useQuery(fetchAllPhrases);

Let’s also add support for Google auth for our app. It involves declaring you want it in the Wasp file, adding some env variables and using it in the React application.

We declare it to the Wasp file by adding the google key under auth:

app phraseTutor {
  ...
  auth: {
    userEntity: User,
    externalAuthEntity: SocialUser,
    methods: {
      // Define we want the Google auth
      google: {
        // Optionally, we can adjust what is saved from the user's data
        getUserFieldsFn: import { getUserFields } from "@server/auth/google.js"
      }
    },
    onAuthFailedRedirectTo: "/"
  },
  ...
}

// Some of the entities needed for auth
entity User {=psl
  id Int @id @default(autoincrement())
  username String @unique
  password String
  profilePicture String
  externalAuthAssociations SocialUser[]
  createdAt DateTime @default(now())
psl=}

entity SocialUser {=psl
  id          Int       @id @default(autoincrement())
  provider    String
  providerId  String
  user        User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  userId      Int
  createdAt   DateTime  @default(now())
  @@unique([provider, providerId, userId])
psl=}

And … that’s it. We can now use the Google auth in our frontend 🎉

import { signInUrl as googleSignInUrl } from "@wasp/auth/helpers/Google";
...
const { data: user } = useAuth();

Writing a full-stack React and Express.js with Wasp felt like a guided experience; I didn't have to focus too hard on the dev tooling, building, or deploying.

Instead, I could focus on the logic needed for Phrase Tutor to work and just run wasp start most of the time. I did need to write some extra code to get everything running, but I'm free to customize this code however I want.

info

Check out the deployed project built with Wasp: https://phrasetutor.com

info

View the source here

Let's compare some of the features​

I want to compare the features of Supabase and Wasp. It's good to think about different ways to do things and their pros and cons.

FeatureSupabaseWasp
Getting data from the APIUse the Supabase JS SDK to query database tablesDeclare query in Wasp config and use Prisma JS SDK to implement it
Custom business logicWriting custom PostgreSQL procedures or by writing edge functionsDeclare actions in the Wasp file and write server-side JS
Defining the database schemaVisual editor or by CREATE TABLE queryBy code - edit Prisma schema and commit changes
AuthEnable in UIEnable it in the Wasp file
DeploymentSupabase managed instance or self-host itDeploy anywhere, support for https://fly.io one line deployment

With Supabase, I liked how familiar the SDK felt and their UI made it easy to configure parts of my backend. I didn’t need to think about deploying Supabase since I used their hosted version, but it did get paused after 1 week of inactivity on the free tier.

On the other hand, Wasp felt like the glue for my React + Express.js + Prisma app and I needed to write more code to get things done. It felt more explicit because I wrote code closer to what I would normally write. I deployed it to fly.io with the Wasp command wasp deploy fly launch and it’s now live on https://phrasetutor.com

Conclusion​

It's all about the use case​

Choosing the right solution for your needs can be difficult. That's why it's important to try out different options and see how they work for you. In this case, I compared two options: Supabase and Wasp.

Supabase is a great choice if you want a well-rounded open-source BaaS product that adds superpowers to your front-end apps. It provides a lot of free stuff, such as a PostgreSQL database and social authentication, which can make development easier and faster. It also has a nice SDK and UI that the end user can use to easily define their app's configuration.

Wasp is an open-source framework for building full-stack apps that helps out with keeping the boilerplate low. It is a bit more explicit about some things, such as defining your auth entities, but that can be a plus when you have more advanced use cases. By using Wasp as the glue for your full-stack application, you can have the best of both worlds: a development and production setup that works out of the box while still allowing you to develop your app any way you like.

In the case of Phrase Tutor, I liked working with both Supabase and Wasp. I did, however, get a different feeling from working with the two technologies. With Supabase I felt like my front-end app got instant superpowers and it now has a database and login, which was nice considering the effort I had to put in. But now I had a black-box dependency that I needed to build around.

When I used Wasp to rebuild Phrase Tutor, it felt different because it was a full-stack app. I had more control over the application code, so I could change it and evolve it as I wanted. I felt like I had built an app that could grow in any direction. Although I had to write more code, it felt like a good trade-off for future needs.

To decide which option is best for you, I would suggest trying both and seeing how you feel. It is easy to set up both tools and see if they make sense for you.

Grazie for reading 🙃
Grazie for reading 🙃

If you try out the Phrase Tutor app, please let me know what you think. You can reach me on Twitter. I'm always looking for ways to make it better.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Building a full-stack app for learning Italian: Supabase vs. Wasp

· 14 min read
Mihovil Ilakovac

wasp vs. supabase

Intro​

What to expect​

In this blog post, I will explain how I created the Phrase Tutor app for learning Italian phrases using two different technologies. I will share some code snippets to show what was required to build the app with both Wasp and Supabase.

Phrase Tutor’s front-end
Phrase Tutor’s front-end

As a senior full-stack developer with experience in building many side-projects, I prefer a quick development cycle. I enjoy turning ideas into POCs in just a few days or even hours.

We will examine how each technology can help when building a full-stack app and where Wasp and Supabase excel.

I wanted to learn Italian fast​

Whenever I travel abroad, I enjoy imagining what it would be like to live in that place. For instance, I usually don't like taking crowded public transportation, but for some reason, it brings me joy when I do it in a foreign country. It's all about the feeling that I'm living there. One of the most important things for me to fully experience the culture is to learn the language or, at the very least, be able to not speak English all the time.

Pretending to be Italian
Pretending to be Italian

My girlfriend and I were planning a trip to Italy, and I wanted to learn some Italian. I thought about what would be the easiest way to learn as much as possible with the least amount of effort. I decided that learning the top 100 Italian phrases would be a good start. I had a week to do it, and learning 100 phrases seemed doable if I practiced every day.

The learning method​

In high school, I had a system for learning historical facts and dates quickly called "focusing on things you don’t know".

Here's how it works:

  1. Gather a pool of facts you want to learn (e.g. "When did WWI start?" - "1914").
  2. Ask yourself each question in the pool.
  3. If you know the answer, remove the fact from the pool.
  4. If you don't know the answer, keep it in the pool.
  5. Repeat with the smaller pool until there are no more facts left.

I made a small app for this and shared it with my classmates, but it didn't go further than that.

Now, I want to use the same method to learn Italian phrases for my trip. So, as a better developer now, I'll make a proper app and host it somewhere 🙂

Building the Phrase Tutor app​

We will create an app that follows the method described above. The app will show you a phrase and you can tell it if you know the translation or not by selecting "I knew it" or "I didn't know it".

How the learning in the app should work
How the learning in the app should work

The app will keep track of your answers and suggest which phrases you should learn next 🕵️

I’ve built the app twice: first with Supabase and then with Wasp. Supabase is a well-rounded open-source Backend as a Service (BaaS) product that adds superpowers to your front-end apps. On the other hand, Wasp is an open-source framework for building full-stack apps that helps to keep the boilerplate low. Let’s see how they compare.

Initial Supabase version​

When I made the initial version, I worked heavily with Vue.js, which I used to create the first version of the Phrase Tutor app. I started by collecting some phrases. I searched on Google for "best Italian phrases to learn" and came across an article titled "100 Italian phrases to learn." (After extracting the phrases from the HTML, I found out that there were only 96 phrases, but that was still good enough for me.)

The initial app contained the phrases in a JSON file that the frontend loaded. It was completely static, but it worked.

{
    "id": 1,
    "group": "general",
    "translations": {
        "en": "Yes",
        "it": "Si"
    }
}

I put it on Cloudflare Pages and it went live.

I showed it to my girlfriend, but she didn't like some of the phrases I used. If only I had a backend with a database to edit the phrases. Then I had an idea: let's add a database with Supabase.

Supabase is a managed backend solution that provides a lot of free stuff: a PostgreSQL database and social authentication among other things.

Phrase Tutor built with Supabase
Phrase Tutor built with Supabase

I set up the database tables using the Supabase UI which was pretty straightforward.

The table I needed only had a few fields:

CREATE TABLE phrases (
    id bigint  NOT NULL,
    group character varying  NULL,
    translations_en text  NOT NULL,
    translations_it text  NOT NULL
);

Then I had to seed the database with some SQL. Executing SQL statements is easy with the use of Supabase’s UI. You just log in, open the SQL editor and paste in the code:

INSERT INTO phrases(id,"group",translations_en,translations_it) VALUES (1,'general','Yes','Si');
INSERT INTO phrases(id,"group",translations_en,translations_it) VALUES (2,'general','No','No');
...

Integrating Supabase into my existing front-end app was simple using their Javascript SDK. If you're familiar with Firebase, it should feel similar. Essentially, you build your SQL queries on the frontend and use the resulting data in your app.

Using the SDK felt pretty straightforward and I could get what I wanted out of the database without much hassle.

const { data, error } = await supabase.from("phrases").select("*");

And just like that, my static Vue.js app had a database to rely on 🎉

Adding the login with Google was a matter of enabling it in Supabase UI and setting up the Client ID and Client Secret variables. In order to trigger the login process with Google, I once again relied on their Javascript SDK.

supabase.auth.signInWithOAuth({ provider: "google" });

Awesome! I'm glad that I can now edit the phrases and that there is a login feature that I plan to use later.

In the future, I have plans to add more languages to the app and also allow registered users to contribute new phrases and translations. I believe this will make the app more useful and engaging for language learners.

And just like that, my app went from a pure static app to an app with a database and Google login 🤯

info

Check out the deployed app written with Vue.js and Supabase: https://phrase-tutor.pages.dev

info

View the source here

Joining Wasp and dogfooding it​

Some background before the second part: I started working at Wasp earlier this year. I'm really happy to work on a technology that solves a problem I care about: when I do side-projects, I dislike writing the same dull parts every time from scratch. I copy and paste from my previous side projects, but eventually, the code snippets become old and outdated.

Naturally, I wanted to test out Wasp by rewriting one of my side projects. I decided to see how Wasp could work with the Phrase Tutor project.

Wasp works by having an easy-to-understand config file called main.wasp which coordinates your pieces of client and server functionalities. Its main purpose is to keep you productive and focused on writing interesting bits. It feels pretty much like using a web framework that covers your whole app.

Phrase Tutor built with Wasp
Phrase Tutor built with Wasp

Let's begin by creating the data models. Wasp uses Prisma under the hood to communicate with your database, which makes it easy to manage your database without worrying about the details. This is just one of the many choices the framework made for me, and I appreciate the feeling of using a setup that works.

I had to first declare all of the entities I needed with Prisma PSL in the Wasp config file.

entity Phrase {=psl
  id Int @id @default(autoincrement())
  group String
  phrase String
  translations Translation[]
psl=}

entity Language {=psl
  id Int @id @default(autoincrement())
  name String @unique
  emoji String
  translations Translation[]
psl=}

entity Translation {=psl
  id Int @id @default(autoincrement())
  phraseId Int
  languageId Int
  translation String
  phrase Phrase @relation(fields: [phraseId], references: [id], onDelete: Cascade)
  language Language @relation(fields: [languageId], references: [id], onDelete: Cascade)
psl=}

I'm using a PostgreSQL database again, and you can see that the field definitions are similar.

I improved the data schema a bit by defining three tables instead of one. I separated the concept of a Phrase from the concepts of Language and Translation. This will make it easier to add new languages in the future.

I added some phrases to the database using Prisma and a Wasp action:

export async function seedItalianPhrases(args, context) {
    const data = [
       {
            id: 1,
            group: "general",
            translations_en: "Yes",
            translations_it: "Si"
        },
        ...
    ]
    for (const phrase of seedPhrases) {
        await context.entities.Phrase.create({
            ...
        });
    }
}

Let’s now look at what I needed to do to get the data flowing from the backend to my React app.

First, I declared a query in my Wasp config file:

app phraseTutor {
  ...
}
...

query fetchAllPhrases {
  fn: import { getAllPhrases } from "@server/queries.js",
  entities: [Phrase]
}

Then I wrote the code for my backend to fetch the phrases. You’ll notice it’s quite similar to the code I wrote for fetching phrases with the Supabase SDK, but I had to include the translations relation since we now have multiple tables.

// My query got the Prisma entity through the context parameter
// which I just used to fetch all the phrases
export async function getAllPhrases(args, context) {
    return context.entities.Phrase.findMany({
        include: {
            translations: true
        }
    });
}

And lastly, I could just import the query into my React app. It’s set up in a way that it handles cache invalidation automatically, one less thing to worry about, which is awesome 😎

// Wasp relies on React Query in the background
const { data: phrases, isLoading } = useQuery(fetchAllPhrases);

Let’s also add support for Google auth for our app. It involves declaring you want it in the Wasp file, adding some env variables and using it in the React application.

We declare it to the Wasp file by adding the google key under auth:

app phraseTutor {
  ...
  auth: {
    userEntity: User,
    externalAuthEntity: SocialUser,
    methods: {
      // Define we want the Google auth
      google: {
        // Optionally, we can adjust what is saved from the user's data
        getUserFieldsFn: import { getUserFields } from "@server/auth/google.js"
      }
    },
    onAuthFailedRedirectTo: "/"
  },
  ...
}

// Some of the entities needed for auth
entity User {=psl
  id Int @id @default(autoincrement())
  username String @unique
  password String
  profilePicture String
  externalAuthAssociations SocialUser[]
  createdAt DateTime @default(now())
psl=}

entity SocialUser {=psl
  id          Int       @id @default(autoincrement())
  provider    String
  providerId  String
  user        User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  userId      Int
  createdAt   DateTime  @default(now())
  @@unique([provider, providerId, userId])
psl=}

And … that’s it. We can now use the Google auth in our frontend 🎉

import { signInUrl as googleSignInUrl } from "@wasp/auth/helpers/Google";
...
const { data: user } = useAuth();

Writing a full-stack React and Express.js with Wasp felt like a guided experience; I didn't have to focus too hard on the dev tooling, building, or deploying.

Instead, I could focus on the logic needed for Phrase Tutor to work and just run wasp start most of the time. I did need to write some extra code to get everything running, but I'm free to customize this code however I want.

info

Check out the deployed project built with Wasp: https://phrasetutor.com

info

View the source here

Let's compare some of the features​

I want to compare the features of Supabase and Wasp. It's good to think about different ways to do things and their pros and cons.

FeatureSupabaseWasp
Getting data from the APIUse the Supabase JS SDK to query database tablesDeclare query in Wasp config and use Prisma JS SDK to implement it
Custom business logicWriting custom PostgreSQL procedures or by writing edge functionsDeclare actions in the Wasp file and write server-side JS
Defining the database schemaVisual editor or by CREATE TABLE queryBy code - edit Prisma schema and commit changes
AuthEnable in UIEnable it in the Wasp file
DeploymentSupabase managed instance or self-host itDeploy anywhere, support for https://fly.io one line deployment

With Supabase, I liked how familiar the SDK felt and their UI made it easy to configure parts of my backend. I didn’t need to think about deploying Supabase since I used their hosted version, but it did get paused after 1 week of inactivity on the free tier.

On the other hand, Wasp felt like the glue for my React + Express.js + Prisma app and I needed to write more code to get things done. It felt more explicit because I wrote code closer to what I would normally write. I deployed it to fly.io with the Wasp command wasp deploy fly launch and it’s now live on https://phrasetutor.com

Conclusion​

It's all about the use case​

Choosing the right solution for your needs can be difficult. That's why it's important to try out different options and see how they work for you. In this case, I compared two options: Supabase and Wasp.

Supabase is a great choice if you want a well-rounded open-source BaaS product that adds superpowers to your front-end apps. It provides a lot of free stuff, such as a PostgreSQL database and social authentication, which can make development easier and faster. It also has a nice SDK and UI that the end user can use to easily define their app's configuration.

Wasp is an open-source framework for building full-stack apps that helps out with keeping the boilerplate low. It is a bit more explicit about some things, such as defining your auth entities, but that can be a plus when you have more advanced use cases. By using Wasp as the glue for your full-stack application, you can have the best of both worlds: a development and production setup that works out of the box while still allowing you to develop your app any way you like.

In the case of Phrase Tutor, I liked working with both Supabase and Wasp. I did, however, get a different feeling from working with the two technologies. With Supabase I felt like my front-end app got instant superpowers and it now has a database and login, which was nice considering the effort I had to put in. But now I had a black-box dependency that I needed to build around.

When I used Wasp to rebuild Phrase Tutor, it felt different because it was a full-stack app. I had more control over the application code, so I could change it and evolve it as I wanted. I felt like I had built an app that could grow in any direction. Although I had to write more code, it felt like a good trade-off for future needs.

To decide which option is best for you, I would suggest trying both and seeing how you feel. It is easy to set up both tools and see if they make sense for you.

Grazie for reading 🙃
Grazie for reading 🙃

If you try out the Phrase Tutor app, please let me know what you think. You can reach me on Twitter. I'm always looking for ways to make it better.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/03/17/new-react-docs-pretend-spas-dont-exist.html b/blog/2023/03/17/new-react-docs-pretend-spas-dont-exist.html index 53d07c7e83..ba678faf22 100644 --- a/blog/2023/03/17/new-react-docs-pretend-spas-dont-exist.html +++ b/blog/2023/03/17/new-react-docs-pretend-spas-dont-exist.html @@ -19,13 +19,13 @@ - - + + -
-

New React docs pretend SPAs don't exist anymore

· 5 min read
Matija Sosic

Where is Vite

React just released their new docs at https://react.dev/. While it looks great and packs a lot of improvements, one section that caught the community’s attention is “Start a New React Project”. The strongly recommended way to start a new React project is to use a framework such as Next.js, while the traditional route of using bundlers like Vite or CRA is fairly strongly discouraged.

Next.js is a great framework, and its rise in popularity is due in a large part to the return of SEO optimization via Server-Side-Rendering (SSR) within the collective developer conscience. And it definitely does make sense to use a framework that provides SSR for static sites and pages that rely on SEO.

But what about typical Single Page Apps (SPAs)? Dashboard-like tools that live behind the auth (and don’t need SEO at all), and for which React was originally designed, still very much exist.

The new React docs - use a framework unless your app has “unusual” constraints​

react new project docs

The new docs make a pretty strong claim for using a framework when starting a new React project. Even if you read through the “Can I use React without a framework” section (hidden behind a collapsed toggle by default), you have to go through a wall of text convincing you why not using a framework is a bad idea, mainly due to the lack of SSR. Only then, in the end, comes the piece mentioning other options, such as Vite and Parcel:

use framework unless you app has unusual constraints

Even then, first you’ll have to admit your app has unusual constraints (and no examples were given of what that could be) before you’re actually “allowed” not to use a framework. It feels very much like you’re doing it in spite of all the warnings and that there actually isn’t a case where you should do it.

Why SPAs (still) matter​

SPAs still have their place

SSR/SSG has been getting a lot of attention lately and has been a flagship feature of most new frameworks built on top of React. And rightly so - it has solved a major issue of using React for static & SEO-facing sites where time to first content (FCP) is crucial.

On the other hand, the use case where React, Angular, and other UI frameworks initially shined were dashboard apps (e.g., project management systems, CRMs, …) - it allowed for a radically better UX, which resembled that of desktop apps.

Although interactive content-rich apps (blogging platforms, marketplaces, social platforms) are today a typical poster child demo app for frameworks, dashboard-like apps still very much exist, and there are more of them than ever. Thousands of companies are building their internal tools daily, just like new SaaS-es pop up every day.

SEO is largely irrelevant for them since everything is happening behind the auth layer, where everything is centered around workflows, not content. SSR might even be counter-productive since it puts more pressure on your servers instead of distributing the rendering load across the clients.

How then would you develop SPAs?​

Traditionally, React was only a UI library in your stack of choice. You would use CRA (or Vite nowadays) as a bundler/starter for your React project. Then you’d probably add a routing library (e.g., react-router) and maybe a state management library (e.g., Redux, or react-query), and you’d already be set pretty well. You would develop your backend in whatever you choose - Node.js/Express, Rails, or anything else.

There are also new frameworks emerging that focus on this particular use case (e.g., RedwoodJS and Wasp (disclaimer: this is us!)) whose flagship feature is not SSR, but rather the abstraction of API and CRUD on data models, and getting full-stack functionality from UI to the database, with extra features such as easy authentication and deployment out of the box.

With a “go for Next or you are unusual” and “you need SSR” message, React is making a strong signal against other solutions that don’t emphasize SSR as their main feature.

So what’s the big deal? Nobody forces you to use SSR in Next/Remix​

That’s correct, but also it’s true that a buy-in into a whole framework is a much bigger step than just opting for a UI library. Frameworks are (more) opinionated and come with many decisions (code structure, architecture, deployment) made upfront for you. Which is great and that’s why they are valuable and why we’ll keep using them.

But, both sides of the story should be presented, and the final call should be left to the developer. React is too useful, valuable, and popular a tool and community to allow itself to skip this step.

Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

New React docs pretend SPAs don't exist anymore

· 5 min read
Matija Sosic

Where is Vite

React just released their new docs at https://react.dev/. While it looks great and packs a lot of improvements, one section that caught the community’s attention is “Start a New React Project”. The strongly recommended way to start a new React project is to use a framework such as Next.js, while the traditional route of using bundlers like Vite or CRA is fairly strongly discouraged.

Next.js is a great framework, and its rise in popularity is due in a large part to the return of SEO optimization via Server-Side-Rendering (SSR) within the collective developer conscience. And it definitely does make sense to use a framework that provides SSR for static sites and pages that rely on SEO.

But what about typical Single Page Apps (SPAs)? Dashboard-like tools that live behind the auth (and don’t need SEO at all), and for which React was originally designed, still very much exist.

The new React docs - use a framework unless your app has “unusual” constraints​

react new project docs

The new docs make a pretty strong claim for using a framework when starting a new React project. Even if you read through the “Can I use React without a framework” section (hidden behind a collapsed toggle by default), you have to go through a wall of text convincing you why not using a framework is a bad idea, mainly due to the lack of SSR. Only then, in the end, comes the piece mentioning other options, such as Vite and Parcel:

use framework unless you app has unusual constraints

Even then, first you’ll have to admit your app has unusual constraints (and no examples were given of what that could be) before you’re actually “allowed” not to use a framework. It feels very much like you’re doing it in spite of all the warnings and that there actually isn’t a case where you should do it.

Why SPAs (still) matter​

SPAs still have their place

SSR/SSG has been getting a lot of attention lately and has been a flagship feature of most new frameworks built on top of React. And rightly so - it has solved a major issue of using React for static & SEO-facing sites where time to first content (FCP) is crucial.

On the other hand, the use case where React, Angular, and other UI frameworks initially shined were dashboard apps (e.g., project management systems, CRMs, …) - it allowed for a radically better UX, which resembled that of desktop apps.

Although interactive content-rich apps (blogging platforms, marketplaces, social platforms) are today a typical poster child demo app for frameworks, dashboard-like apps still very much exist, and there are more of them than ever. Thousands of companies are building their internal tools daily, just like new SaaS-es pop up every day.

SEO is largely irrelevant for them since everything is happening behind the auth layer, where everything is centered around workflows, not content. SSR might even be counter-productive since it puts more pressure on your servers instead of distributing the rendering load across the clients.

How then would you develop SPAs?​

Traditionally, React was only a UI library in your stack of choice. You would use CRA (or Vite nowadays) as a bundler/starter for your React project. Then you’d probably add a routing library (e.g., react-router) and maybe a state management library (e.g., Redux, or react-query), and you’d already be set pretty well. You would develop your backend in whatever you choose - Node.js/Express, Rails, or anything else.

There are also new frameworks emerging that focus on this particular use case (e.g., RedwoodJS and Wasp (disclaimer: this is us!)) whose flagship feature is not SSR, but rather the abstraction of API and CRUD on data models, and getting full-stack functionality from UI to the database, with extra features such as easy authentication and deployment out of the box.

With a “go for Next or you are unusual” and “you need SSR” message, React is making a strong signal against other solutions that don’t emphasize SSR as their main feature.

So what’s the big deal? Nobody forces you to use SSR in Next/Remix​

That’s correct, but also it’s true that a buy-in into a whole framework is a much bigger step than just opting for a UI library. Frameworks are (more) opinionated and come with many decisions (code structure, architecture, deployment) made upfront for you. Which is great and that’s why they are valuable and why we’ll keep using them.

But, both sides of the story should be presented, and the final call should be left to the developer. React is too useful, valuable, and popular a tool and community to allow itself to skip this step.

Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/04/11/wasp-launch-week-two.html b/blog/2023/04/11/wasp-launch-week-two.html index 8e6ef398d2..fa9ccdebcd 100644 --- a/blog/2023/04/11/wasp-launch-week-two.html +++ b/blog/2023/04/11/wasp-launch-week-two.html @@ -19,13 +19,13 @@ - - + + -
-

Wasp Launch Week #2

· 7 min read
Matija Sosic

Here we go again! After three months of building and talking to our community about what features they'd like to see next, we're proud to kick off our second Launch Week. It stars tomorrow, and you can sign up for the launch event here!

Launch Week 2 is coming

Wasp Beta introduced a lot of core features that enabled developers to a build full-fledged SaaS-es. Since then, our community grew rapidly and we watched you deploy numerous apps and some of you even making their startups and earning their first revenue on top of Wasp!

Seeing that all the essential building blocks are now in place, our next goal became to make Wasp really easy (and fun) to use. We've had a bunch of ideas on everything we'd like to improve with DX for a while, and now finally came the right time to do it.

Nonetheless, the theme and sentiment of this launch week is best captured by an ancient term that poets used to describe some of the most beautiful and marvelous wonders of the world (e.g. pyramids, or the hanging gardens of Babylon): pizzazz 🍕.

Wednesday, Apr 12 - Launch event 🚀 + Pizzazz opener: Auth UI 💅​

Wasp's easy auth has been by a long shot one of the most popular features in the community. We decided to take it one step further - Wasp now offers beautifully designed, pre-made auth components that you can simply plug into your app and immediately get that razzle dazzle on!

Auth UI Demo
On your localhost, tomorrow

We'll present this and much more at our Kick-off event, starting tomorrow on our Discord at 10 am EDT / 4 pm CET - sign up here and make sure to mark yourself as interested!

Join us to meet the team and to be the first to get a sneak peek into the latest features! We'll follow up with a casual AMA session, showcase selected community projects and discuss all together about what we'd like to see in Wasp next.

LW2 launch party instructions

P.S. : The word is out that there will be a raffle and that the most lucky one(s) will win some cool Wasp swag! (Da Boi included, ofc).

Thursday, Apr 13 - Deploy your app to Fly.io with a single CLI command​

Deploying to Fly.io

When developing your app is blazingly fast, the last thing you want to slow you down is deployment. Figuring out how to exactly setup client/server, dealing with CORS, configuring ports and env vars, ... - well, now you don't have to think about it anymore!

This release of Wasp introduces first CLI deployment helper, for Fly.io (others coming soon, and you're free to contribute)!

How deployment feels now
Deployment in Wasp before vs now

Friday, Apr 14 - Improved database tooling & DX​

Database seeding

Introducing two main quality-of-life features here:

  • wasp start db - Fully managed development database - (don't ever run docker run postgres ... again)
  • Database seeding - populate your database with some initial, "seed" data

This was something we ourselves ended up needing often when developing a new app, and although not a huge thing at the first glance, it's feels so good to have it taken care of! Given that Wasp is a fully managed full-stack framework that "understands" all parts of your dev process, we were in unique position to offer this functionality.

P.S. - you haven't been connecting to the prod database all along during development, have you?

Saturday, Apr 15 - More launch goodness: Custom API routes + Email sending ✉️​

It's Saturday, so you get two features for the price of one!

Add custom API routes​

Custom API routes
Adding a custom route handler at /foo/bar endpoint

Although for typical CRUD you don't have to define an API since Wasp offers a typesafe RPC layer via operations, sometimes you need extra flexibility (e.g. for implementing webhooks). Now you can easily do it, in a typical boilerplate-free Wasp style.

Email sending: Wasp + Sendgrid/Mailgun/...​

Laurence Fishburne messenger pigeons
Don't end up like this, use Wasp for sending emails

Email sending - another feature that sounds like you should be able to implement it in 30 minutes (looking at you, auth), but then you find yourselves a week later cursing web development and having an inexplicable urge to start breeding messenger pigeons (that's what happened to Laurence Fishburne in John Wick, if you ever wondered).

Email sending code example

Wasp offers unified interface for different providers (e.g. Sendgrid or Mailgun, or a custom SMTP server). It also works great with our latest auth method, email - you get email verification and password reset out of the box!

Sunday, Apr 16 - Frontend testing and full-stack type safety!​

We continue with our buy-one-get-one-free scheme (although both are free in all fairness):

Frontend testing, powered by Vitest​

Frontend testing via Vitest

All you have to do to run your frontend tests is run wasp test client in your CLI! Backed by Vitest, while mocking is powered by MSW and additional Wasp helpers sprinkled on top. Now you really have no excuses to write your tests (except on the backend, support for them is coming next, so enjoy while it lasts)!

Full-stack type safety​

Our RPC is now doing serious type-fu
Our typesafe RPC is now doing some serious type-fu

We already introduced glimpses of this in our Beta launch, but now things got even better! Whatever types you define and use on the server, be it entities or your custom types, they immediately get propagated to the client and typecheck in your IDE.

Monday, Apr 17 - SaaS GPT template + Waspathon #2 kick-off!​

SaaS GPT template

Aaand we saved the best for the last - we'll put a special highlight on our SaaS GPT starter, which lets you build GPT-powered apps (such as CoverLetterGPT.xyz or SocialPostGPT.xyz) in a day and with all the good stuff pre-included - auth (social, email), Tailwind, deployment, Stripe and GPT API integration, ... - all you need to do is run it and start coding!

Our second hackathon - Waspathon #2!​

Hacking away
Hate it when this happens.

And what a better reason to try out the SaaS GPT template than a hackathon! It will be an open format and you're free to build whatever you want - there will be a few categories will grade and award, but more on that coming soon!

The same for the prizes - expect cool wasp-themed swag and useful stuff that makes dev's life easier (no, it doesn't include getting rid of your PM).

We'll share more info and the registration link soon.

Recap​

  • We are kicking off Launch Week #2 on Wed, April 12, at 10am EDT / 4pm CET - make sure to register for the event!
  • Launch Week #2 brings a ton of new exciting features - we’ll highlight one each day, starting tomorrow
  • On Monday, April 17, we’ll announce a hackathon - follow us on twitter and join our Discord to stay in the loop!

That’s it, Waspeteers - put your pizzazz (buzzazz?) on and see you tomorrow! 🐝

Matija, Martin & the Wasp team

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Wasp Launch Week #2

· 7 min read
Matija Sosic

Here we go again! After three months of building and talking to our community about what features they'd like to see next, we're proud to kick off our second Launch Week. It stars tomorrow, and you can sign up for the launch event here!

Launch Week 2 is coming

Wasp Beta introduced a lot of core features that enabled developers to a build full-fledged SaaS-es. Since then, our community grew rapidly and we watched you deploy numerous apps and some of you even making their startups and earning their first revenue on top of Wasp!

Seeing that all the essential building blocks are now in place, our next goal became to make Wasp really easy (and fun) to use. We've had a bunch of ideas on everything we'd like to improve with DX for a while, and now finally came the right time to do it.

Nonetheless, the theme and sentiment of this launch week is best captured by an ancient term that poets used to describe some of the most beautiful and marvelous wonders of the world (e.g. pyramids, or the hanging gardens of Babylon): pizzazz 🍕.

Wednesday, Apr 12 - Launch event 🚀 + Pizzazz opener: Auth UI 💅​

Wasp's easy auth has been by a long shot one of the most popular features in the community. We decided to take it one step further - Wasp now offers beautifully designed, pre-made auth components that you can simply plug into your app and immediately get that razzle dazzle on!

Auth UI Demo
On your localhost, tomorrow

We'll present this and much more at our Kick-off event, starting tomorrow on our Discord at 10 am EDT / 4 pm CET - sign up here and make sure to mark yourself as interested!

Join us to meet the team and to be the first to get a sneak peek into the latest features! We'll follow up with a casual AMA session, showcase selected community projects and discuss all together about what we'd like to see in Wasp next.

LW2 launch party instructions

P.S. : The word is out that there will be a raffle and that the most lucky one(s) will win some cool Wasp swag! (Da Boi included, ofc).

Thursday, Apr 13 - Deploy your app to Fly.io with a single CLI command​

Deploying to Fly.io

When developing your app is blazingly fast, the last thing you want to slow you down is deployment. Figuring out how to exactly setup client/server, dealing with CORS, configuring ports and env vars, ... - well, now you don't have to think about it anymore!

This release of Wasp introduces first CLI deployment helper, for Fly.io (others coming soon, and you're free to contribute)!

How deployment feels now
Deployment in Wasp before vs now

Friday, Apr 14 - Improved database tooling & DX​

Database seeding

Introducing two main quality-of-life features here:

  • wasp start db - Fully managed development database - (don't ever run docker run postgres ... again)
  • Database seeding - populate your database with some initial, "seed" data

This was something we ourselves ended up needing often when developing a new app, and although not a huge thing at the first glance, it's feels so good to have it taken care of! Given that Wasp is a fully managed full-stack framework that "understands" all parts of your dev process, we were in unique position to offer this functionality.

P.S. - you haven't been connecting to the prod database all along during development, have you?

Saturday, Apr 15 - More launch goodness: Custom API routes + Email sending ✉️​

It's Saturday, so you get two features for the price of one!

Add custom API routes​

Custom API routes
Adding a custom route handler at /foo/bar endpoint

Although for typical CRUD you don't have to define an API since Wasp offers a typesafe RPC layer via operations, sometimes you need extra flexibility (e.g. for implementing webhooks). Now you can easily do it, in a typical boilerplate-free Wasp style.

Email sending: Wasp + Sendgrid/Mailgun/...​

Laurence Fishburne messenger pigeons
Don't end up like this, use Wasp for sending emails

Email sending - another feature that sounds like you should be able to implement it in 30 minutes (looking at you, auth), but then you find yourselves a week later cursing web development and having an inexplicable urge to start breeding messenger pigeons (that's what happened to Laurence Fishburne in John Wick, if you ever wondered).

Email sending code example

Wasp offers unified interface for different providers (e.g. Sendgrid or Mailgun, or a custom SMTP server). It also works great with our latest auth method, email - you get email verification and password reset out of the box!

Sunday, Apr 16 - Frontend testing and full-stack type safety!​

We continue with our buy-one-get-one-free scheme (although both are free in all fairness):

Frontend testing, powered by Vitest​

Frontend testing via Vitest

All you have to do to run your frontend tests is run wasp test client in your CLI! Backed by Vitest, while mocking is powered by MSW and additional Wasp helpers sprinkled on top. Now you really have no excuses to write your tests (except on the backend, support for them is coming next, so enjoy while it lasts)!

Full-stack type safety​

Our RPC is now doing serious type-fu
Our typesafe RPC is now doing some serious type-fu

We already introduced glimpses of this in our Beta launch, but now things got even better! Whatever types you define and use on the server, be it entities or your custom types, they immediately get propagated to the client and typecheck in your IDE.

Monday, Apr 17 - SaaS GPT template + Waspathon #2 kick-off!​

SaaS GPT template

Aaand we saved the best for the last - we'll put a special highlight on our SaaS GPT starter, which lets you build GPT-powered apps (such as CoverLetterGPT.xyz or SocialPostGPT.xyz) in a day and with all the good stuff pre-included - auth (social, email), Tailwind, deployment, Stripe and GPT API integration, ... - all you need to do is run it and start coding!

Our second hackathon - Waspathon #2!​

Hacking away
Hate it when this happens.

And what a better reason to try out the SaaS GPT template than a hackathon! It will be an open format and you're free to build whatever you want - there will be a few categories will grade and award, but more on that coming soon!

The same for the prizes - expect cool wasp-themed swag and useful stuff that makes dev's life easier (no, it doesn't include getting rid of your PM).

We'll share more info and the registration link soon.

Recap​

  • We are kicking off Launch Week #2 on Wed, April 12, at 10am EDT / 4pm CET - make sure to register for the event!
  • Launch Week #2 brings a ton of new exciting features - we’ll highlight one each day, starting tomorrow
  • On Monday, April 17, we’ll announce a hackathon - follow us on twitter and join our Discord to stay in the loop!

That’s it, Waspeteers - put your pizzazz (buzzazz?) on and see you tomorrow! 🐝

Matija, Martin & the Wasp team

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/04/12/auth-ui.html b/blog/2023/04/12/auth-ui.html index cef7c51aa3..fdf1a8f7ac 100644 --- a/blog/2023/04/12/auth-ui.html +++ b/blog/2023/04/12/auth-ui.html @@ -19,13 +19,13 @@ - - + + -
-

Wasp Auth UI: The first full-stack auth with self-updating forms!

· 2 min read
Matija Sosic

One of the main benefits of Wasp is having deep understanding of your entire full-stack app - e.g. what routes you have, what data models you defined, but also what methods you use for authentication. And that enables us to do some pretty cool stuff for you!

Auth UI Demo
Customize auth forms to fit your brand!

Once you've listed auth methods you want to use in your .wasp config file, you're done - from that Wasp generates a full authentication form that you simply import as a React component. And the best part is that is updates dynamically as you add/remove auth providers!

You can see the docs and give it a try here.

Auto-updating magic 🔮​

Auth UI Demo gif
Add GitHub as another auth provider -> the form updates automatically!

tip

Since .wasp config file contains a high-level description of your app's requirements, Wasp can deduce a lot of stuff for you from it, and this is just a single example.

When you update your .wasp file by adding/removing an auth method (GitHub in this case), Wasp will detect it and automatically regenerate the auth form. No need to configure anything else, or change your React code - just a single line change in .wasp file and everything else will get taken care of!

Mind exploding
When you realize Wasp is a compiler and actually understands your app 🤯

Customize it! 🎨​

Although it looks nice, all of this wouldn't be really useful if you couldn't customize it to fit your brand. That's easily done through the component's props:

Customizing auth form through props
Easily customize your auth form through props!

And that's it! You can see the whole list of tokens you can customize here. More are coming in the future!

Wasp out 🐝 🎤- give it a try and let us know how you liked it in our Discord !

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Wasp Auth UI: The first full-stack auth with self-updating forms!

· 2 min read
Matija Sosic

One of the main benefits of Wasp is having deep understanding of your entire full-stack app - e.g. what routes you have, what data models you defined, but also what methods you use for authentication. And that enables us to do some pretty cool stuff for you!

Auth UI Demo
Customize auth forms to fit your brand!

Once you've listed auth methods you want to use in your .wasp config file, you're done - from that Wasp generates a full authentication form that you simply import as a React component. And the best part is that is updates dynamically as you add/remove auth providers!

You can see the docs and give it a try here.

Auto-updating magic 🔮​

Auth UI Demo gif
Add GitHub as another auth provider -> the form updates automatically!

tip

Since .wasp config file contains a high-level description of your app's requirements, Wasp can deduce a lot of stuff for you from it, and this is just a single example.

When you update your .wasp file by adding/removing an auth method (GitHub in this case), Wasp will detect it and automatically regenerate the auth form. No need to configure anything else, or change your React code - just a single line change in .wasp file and everything else will get taken care of!

Mind exploding
When you realize Wasp is a compiler and actually understands your app 🤯

Customize it! 🎨​

Although it looks nice, all of this wouldn't be really useful if you couldn't customize it to fit your brand. That's easily done through the component's props:

Customizing auth form through props
Easily customize your auth form through props!

And that's it! You can see the whole list of tokens you can customize here. More are coming in the future!

Wasp out 🐝 🎤- give it a try and let us know how you liked it in our Discord !

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/04/13/db-start-and-seed.html b/blog/2023/04/13/db-start-and-seed.html index ab3f2bfe54..8412183162 100644 --- a/blog/2023/04/13/db-start-and-seed.html +++ b/blog/2023/04/13/db-start-and-seed.html @@ -19,13 +19,13 @@ - - + + -
-

Wasp steps up its database game with Fully Managed Dev DB & DB Seeding

· 6 min read
Martin Sosic

As a full-stack framework, Wasp doesn’t care “just” about frontend and backend, but it also covers the database!

It does this by allowing you to define Prisma data models in a Wasp file, connecting them to the relevant Wasp Operations, warning you if you need to do database migrations, deploying the database for you (if you choose so), … .

Since Wasp knows so much about your database, that puts us in a good position to keep finding ways to improve the developer experience regarding dealing with the database. For Wasp v0.10, we focused on:

  1. Wasp running the dev database for you with no config needed → Fully Managed Dev Database 🚀
  2. Wasp helping you to initialize the database with some data → Db Seeding 🌱

strong wasp database
Wasp now has `wasp start db` and `wasp db seed`!

Fully Managed Dev Database 🚀​

You might have asked yourself:

If Wasp already knows so much about my database, why do I need to bother running it on my own!?

Ok, when you start a new Wasp project it is easy because you are using an SQLite database, but once you switch to Postgres, it falls onto you to take care of it: run it, provide its URL to Wasp via env var, handle multiple databases if you have multiple Wasp apps, … .

This can get tedious quickly, especially if you are visiting your Wasp project that you haven’t worked on for a bit and need to figure out again how to run the db, or you need to check out somebody else’s Wasp project and don’t have it all set up yet. It is something most of us are used to, especially with other frameworks, but still, we can do better at Wasp!

This is where wasp start db comes in!

wasp start db running in terminal
wasp start db in action, running a posgtres dev db for you

Now, all you need to do to run the development database, is run wasp start db, and Wasp will run it for you and will know how to connect to it during development.

No env var setting, no remembering how to run the db. The only requirement is that you have Docker installed on your machine. Data from your database will be persisted on the disk between the runs, and each Wasp app will have its own database assigned.

Btw, you can still use a custom database that you ran on your own if you want, the same way it was done before in Wasp: by setting env var DATABASE_URL.

Database seeding 🌱​

Database seeding is a term for populating the database with some initial data.

Seeding is most commonly used for two following scenarios:

  1. To put the development database into a state convenient for testing / playing with it.
  2. To initialize the dev/staging/prod database with some essential data needed for it to be useful, for example, default currencies in a Currency table.

Wasp so far had no direct support for seeding, so you had to either come up with your own solution (e.g. script that connects to the db and executes some queries), or massage data manually via Prisma Studio (wasp db studio).

There is one big drawback to both of the approaches I mentioned above though: there is no easy way to reuse logic that you have already implemented in your Wasp app, especially Actions (e.g. createTask)! This is pretty bad, as it makes your seeding logic brittle.

This is where wasp db seed comes in! Now, Wasp allows you to write a JS/TS function, import any server logic (including Actions) into it as you wish, and then seed the database with it.

wasp db seed running in terminal
wasp db seed in action, initializing the db with dev data

Registering seed functions in Wasp is easy:

app MyApp {
  // ...
  db: {
    // ...
    seeds: [
      import { devSeedSimple } from "@server/dbSeeds.js",
      import { prodSeed } from "@server/dbSeeds.js"
    ]
  }
}

Example of a seed function from above, devSeedSimple:

import { createTask } from './actions.js'

export const devSeedSimple = async (prismaClient) => {
  const user = await createUser(prismaClient, {
      username: "RiuTheDog",
      password: "bark1234"
  })

  await createTask(
    { description: "Chase the cat" },
    { user, entities: { Task: prismaClient.task } }
  )
}

async function createUser (prismaClient, data) {
  const { password, ...newUser } = await prismaClient.user.create({ data })
  return newUser
}

Finally, to run these seeds, you can either do:

  • wasp db seed: If you have just one seed function, it will run it. If you have multiple, it will interactively ask you to choose one to run.
  • wasp db seed <seed-name>: It will run the seed function with the specified name, where the name is the identifier you used in its import expression in the app.db.seeds list. Example: wasp db seed devSeedSimple.

We also added wasp db reset command (calls prisma db reset in the background) that cleans up the database for you (removes all data and tables and re-applies migrations), which is great to use in combination with wasp db seed, as a precursor.

Plans for the future 🔮​

  • allow customization of managed dev database (Postgres plugins, custom Dockerfile, …)
  • have Wasp run the managed dev database automatically whenever it needs it (instead of you having to run wasp start db manually)
  • dynamically find a free port for managed dev database (right now it requires port 5432)
  • provide utility functions to make writing seeding functions easier (e.g. functions for creating new users)
  • right now seeding functions are defined as part of a Wasp server code → it might be interesting to separate them in a standalone “project” in the future, while still keeping their easy access to the server logic.
  • do you have any ideas/suggestions? Let us know in our Discord !
Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Wasp steps up its database game with Fully Managed Dev DB & DB Seeding

· 6 min read
Martin Sosic

As a full-stack framework, Wasp doesn’t care “just” about frontend and backend, but it also covers the database!

It does this by allowing you to define Prisma data models in a Wasp file, connecting them to the relevant Wasp Operations, warning you if you need to do database migrations, deploying the database for you (if you choose so), … .

Since Wasp knows so much about your database, that puts us in a good position to keep finding ways to improve the developer experience regarding dealing with the database. For Wasp v0.10, we focused on:

  1. Wasp running the dev database for you with no config needed → Fully Managed Dev Database 🚀
  2. Wasp helping you to initialize the database with some data → Db Seeding 🌱

strong wasp database
Wasp now has `wasp start db` and `wasp db seed`!

Fully Managed Dev Database 🚀​

You might have asked yourself:

If Wasp already knows so much about my database, why do I need to bother running it on my own!?

Ok, when you start a new Wasp project it is easy because you are using an SQLite database, but once you switch to Postgres, it falls onto you to take care of it: run it, provide its URL to Wasp via env var, handle multiple databases if you have multiple Wasp apps, … .

This can get tedious quickly, especially if you are visiting your Wasp project that you haven’t worked on for a bit and need to figure out again how to run the db, or you need to check out somebody else’s Wasp project and don’t have it all set up yet. It is something most of us are used to, especially with other frameworks, but still, we can do better at Wasp!

This is where wasp start db comes in!

wasp start db running in terminal
wasp start db in action, running a posgtres dev db for you

Now, all you need to do to run the development database, is run wasp start db, and Wasp will run it for you and will know how to connect to it during development.

No env var setting, no remembering how to run the db. The only requirement is that you have Docker installed on your machine. Data from your database will be persisted on the disk between the runs, and each Wasp app will have its own database assigned.

Btw, you can still use a custom database that you ran on your own if you want, the same way it was done before in Wasp: by setting env var DATABASE_URL.

Database seeding 🌱​

Database seeding is a term for populating the database with some initial data.

Seeding is most commonly used for two following scenarios:

  1. To put the development database into a state convenient for testing / playing with it.
  2. To initialize the dev/staging/prod database with some essential data needed for it to be useful, for example, default currencies in a Currency table.

Wasp so far had no direct support for seeding, so you had to either come up with your own solution (e.g. script that connects to the db and executes some queries), or massage data manually via Prisma Studio (wasp db studio).

There is one big drawback to both of the approaches I mentioned above though: there is no easy way to reuse logic that you have already implemented in your Wasp app, especially Actions (e.g. createTask)! This is pretty bad, as it makes your seeding logic brittle.

This is where wasp db seed comes in! Now, Wasp allows you to write a JS/TS function, import any server logic (including Actions) into it as you wish, and then seed the database with it.

wasp db seed running in terminal
wasp db seed in action, initializing the db with dev data

Registering seed functions in Wasp is easy:

app MyApp {
  // ...
  db: {
    // ...
    seeds: [
      import { devSeedSimple } from "@server/dbSeeds.js",
      import { prodSeed } from "@server/dbSeeds.js"
    ]
  }
}

Example of a seed function from above, devSeedSimple:

import { createTask } from './actions.js'

export const devSeedSimple = async (prismaClient) => {
  const user = await createUser(prismaClient, {
      username: "RiuTheDog",
      password: "bark1234"
  })

  await createTask(
    { description: "Chase the cat" },
    { user, entities: { Task: prismaClient.task } }
  )
}

async function createUser (prismaClient, data) {
  const { password, ...newUser } = await prismaClient.user.create({ data })
  return newUser
}

Finally, to run these seeds, you can either do:

  • wasp db seed: If you have just one seed function, it will run it. If you have multiple, it will interactively ask you to choose one to run.
  • wasp db seed <seed-name>: It will run the seed function with the specified name, where the name is the identifier you used in its import expression in the app.db.seeds list. Example: wasp db seed devSeedSimple.

We also added wasp db reset command (calls prisma db reset in the background) that cleans up the database for you (removes all data and tables and re-applies migrations), which is great to use in combination with wasp db seed, as a precursor.

Plans for the future 🔮​

  • allow customization of managed dev database (Postgres plugins, custom Dockerfile, …)
  • have Wasp run the managed dev database automatically whenever it needs it (instead of you having to run wasp start db manually)
  • dynamically find a free port for managed dev database (right now it requires port 5432)
  • provide utility functions to make writing seeding functions easier (e.g. functions for creating new users)
  • right now seeding functions are defined as part of a Wasp server code → it might be interesting to separate them in a standalone “project” in the future, while still keeping their easy access to the server logic.
  • do you have any ideas/suggestions? Let us know in our Discord !
Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/04/17/How-I-Built-CoverLetterGPT.html b/blog/2023/04/17/How-I-Built-CoverLetterGPT.html index 0a5dd51872..29668748a4 100644 --- a/blog/2023/04/17/How-I-Built-CoverLetterGPT.html +++ b/blog/2023/04/17/How-I-Built-CoverLetterGPT.html @@ -19,13 +19,13 @@ - - + + -
-

How I Built CoverLetterGPT - SaaS app with the PERN stack, GPT, Stripe, & Chakra UI

· 3 min read
Vinny

Like many other software developers, I enjoy trying out new technologies even if it's just to get a feel for what they can do.

So when I first learned about the OpenAI API, I knew I wanted to give it a try. I had already wanted to create a SaaS app that could help manage the process of applying to numerous jobs, and the prospect of adding GPT into the mix made it even more interesting. So with API access and a bit of free time, I decided to give it a shot.

I threw together a simple version of the app in about 3-4 days and CoverLetterGPT was born, a SaaS app that uses GPT-3.5-turbo to generate, revise, and manage cover letters for you based on your skills and the specific job descriptions.

Even though I did think it had potential as a SaaS app, I was approaching it mostly as a way to learn how to build one for the first time. And after seeing so many people "building in public" and sharing their progress, I thought it would be fun to try it out myself.

Hey peeps. Check out http://coverlettergpt.xyz. You can try it out now and create your own cover letters for free (no Payment/API key). I'm working on A LOT more features. Stay Tuned!

So I started sharing my progress on Twitter, Reddit, and Indie Hackers. I made my first post about it on March 9th, and because I was just experimenting and trying my hand at a SaaS app for the first time, I also open-sourced the app to share the code and what I was learning with others. This led to a lot of interest and great feedback, and I ended up getting featured in the indiehackers newsletter, which led to even more interest.

Within the first month, I got over 1,000 sign-ups along with my first paying customers. Pretty surprising, to say the least!

So to continue in the spirit of curiosity, learning, and just "wingin' it," I decided to make a code walkthrough video that explains how I built the app, the tools I used to build it, and a little bit about how I marketed the app without spending any money.

As an extra bonus, I also give a quick introduction to the free SaaS template I created for building your own SaaS app, with or without GPT, on the PERN stack (PostgreSQL/Prisma, Express, React, NodeJS).

My hope is that others will learn something from my experience, and that it could inspire them to try out new technologies and build that app idea they've had in mind (and if they do, they should make sure to share it with me on Twitter @hot_town -- I'd love to see it!)

Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

How I Built CoverLetterGPT - SaaS app with the PERN stack, GPT, Stripe, & Chakra UI

· 3 min read
Vinny

Like many other software developers, I enjoy trying out new technologies even if it's just to get a feel for what they can do.

So when I first learned about the OpenAI API, I knew I wanted to give it a try. I had already wanted to create a SaaS app that could help manage the process of applying to numerous jobs, and the prospect of adding GPT into the mix made it even more interesting. So with API access and a bit of free time, I decided to give it a shot.

I threw together a simple version of the app in about 3-4 days and CoverLetterGPT was born, a SaaS app that uses GPT-3.5-turbo to generate, revise, and manage cover letters for you based on your skills and the specific job descriptions.

Even though I did think it had potential as a SaaS app, I was approaching it mostly as a way to learn how to build one for the first time. And after seeing so many people "building in public" and sharing their progress, I thought it would be fun to try it out myself.

Hey peeps. Check out http://coverlettergpt.xyz. You can try it out now and create your own cover letters for free (no Payment/API key). I'm working on A LOT more features. Stay Tuned!

So I started sharing my progress on Twitter, Reddit, and Indie Hackers. I made my first post about it on March 9th, and because I was just experimenting and trying my hand at a SaaS app for the first time, I also open-sourced the app to share the code and what I was learning with others. This led to a lot of interest and great feedback, and I ended up getting featured in the indiehackers newsletter, which led to even more interest.

Within the first month, I got over 1,000 sign-ups along with my first paying customers. Pretty surprising, to say the least!

So to continue in the spirit of curiosity, learning, and just "wingin' it," I decided to make a code walkthrough video that explains how I built the app, the tools I used to build it, and a little bit about how I marketed the app without spending any money.

As an extra bonus, I also give a quick introduction to the free SaaS template I created for building your own SaaS app, with or without GPT, on the PERN stack (PostgreSQL/Prisma, Express, React, NodeJS).

My hope is that others will learn something from my experience, and that it could inspire them to try out new technologies and build that app idea they've had in mind (and if they do, they should make sure to share it with me on Twitter @hot_town -- I'd love to see it!)

Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/04/27/wasp-hackathon-two.html b/blog/2023/04/27/wasp-hackathon-two.html index 524f5c7492..d7149a058c 100644 --- a/blog/2023/04/27/wasp-hackathon-two.html +++ b/blog/2023/04/27/wasp-hackathon-two.html @@ -19,13 +19,13 @@ - - + + -
-

Wasp Hackathon #2 - Let's "hack-a-ton"!

· 2 min read
Vinny

So Launch Week #2 has officially come to an end, and as the tradition goes, the end of the launch week means the beginning of a hackathon!

We've launched a ton of new features for you to build your Hackathon project with, including:

You can read all it in this blog post, or watch a 1-minute video showing how it all works in practice 🎬!

Launch Week #2 Features -- YouTube Short
Launch Week #2 Features -- YouTube Short

Even better, we've got a new starter templates feature that lets you create a new project with a pre-built template, so you can get started even faster! Like this sweet SaaS template with GPT, Stripe, SendGrid, and Tailwind UI already integrated:

Wasp SaaS Template w/ GPT, Stripe, and more 🎊

Just run wasp new my-project -t saas and you're good to go.

The prizes for the hackathon include an awesome Wasp-themed mechanical keyboard, tons of Wasp swag, and more cool stuff (e.g., virtual hugs from the team)!

The only rule is to use Wasp, and you can build whatever you want (but both you and I know it's going to be a GPT-powered app, so make sure to use our template).

The applications are open, and the hackathon starts on April 28th and ends May 7th. You can apply (solo or with a team) here:


Good luck and Happy Hacking 🐝🚀!


Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Wasp Hackathon #2 - Let's "hack-a-ton"!

· 2 min read
Vinny

So Launch Week #2 has officially come to an end, and as the tradition goes, the end of the launch week means the beginning of a hackathon!

We've launched a ton of new features for you to build your Hackathon project with, including:

You can read all it in this blog post, or watch a 1-minute video showing how it all works in practice 🎬!

Launch Week #2 Features -- YouTube Short
Launch Week #2 Features -- YouTube Short

Even better, we've got a new starter templates feature that lets you create a new project with a pre-built template, so you can get started even faster! Like this sweet SaaS template with GPT, Stripe, SendGrid, and Tailwind UI already integrated:

Wasp SaaS Template w/ GPT, Stripe, and more 🎊

Just run wasp new my-project -t saas and you're good to go.

The prizes for the hackathon include an awesome Wasp-themed mechanical keyboard, tons of Wasp swag, and more cool stuff (e.g., virtual hugs from the team)!

The only rule is to use Wasp, and you can build whatever you want (but both you and I know it's going to be a GPT-powered app, so make sure to use our template).

The applications are open, and the hackathon starts on April 28th and ends May 7th. You can apply (solo or with a team) here:


Good luck and Happy Hacking 🐝🚀!


Want to stay in the loop? → Join our newsletter!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/05/19/hackathon-2-review.html b/blog/2023/05/19/hackathon-2-review.html index 64fb1e1d61..eb3b98f96f 100644 --- a/blog/2023/05/19/hackathon-2-review.html +++ b/blog/2023/05/19/hackathon-2-review.html @@ -19,13 +19,13 @@ - - + + -
-

Hackathon #2: Results & Review

· 6 min read
Vinny

To finalize Wasp's Launch Week #2, we held our second Hackathon. Just like the "Betathon" before it, it was an open hackathon where the only requirement was to build something cool with Wasp!

In this post, I’ll give a quick overview of:

  • the hackathon results 🏆
  • how the hackathon was organized
  • how we promoted it
  • the community response

…and the Winners Are:​

What’s a hackathon without the participants!? Let’s get this post off to a proper start by congratulating our winners and showcasing their work. 🔍

🥇 Typergotchi​

Typergotchi

Our unofficial mascot, Da Boi, makes his debut app appearance in this fun, feature-rich typing game!

“Wasp makes building fullstack apps fast and fun. We've done lots of hackthons in the past, and we couldn't pass up the chance to win a mechanical keyboard :)” - Umbrien & kg04ls

🥈 Office Wars​

Office Wars

A turn-based, multi-player strategy game where you command your tank across a hexagonal map. A great way to keep your coworkers engaged while you wait for your code to compile!

“We love how Wasp brings the tools that are already being used by developers under the same umbrella. It's very streamlined and makes building fullstack apps easy to accomplish... like django but w/ more superpowers” - Roland & Luís

🥉 Tied for Third: Bee Pretty & StorAI​

Bee Pretty

StorAI

After 5 minutes of working with Wasp I thought, this is phenomenal! So much just works out of the box -- everything was flawless" - mkinkela1

🥳 And A Big Round of Applause for the Rest of the Participants!​

Thanks so much to rest of the participants:

  • Max for submitting Feedback Hub, which we award "the most SaaS-y app".
  • Richard for submitting Promise, for winning the "best last-minute minimal-effort submission" award.
  • Swarnavo for submitting his Dashboard Panel app.

Hackathon How-to​

For our first hackathon, the "Betathon", we announced and started it on the final day of our launch week. Looking back, this probably wasn't the best approach because it didn't give people much time to prepare. This time around, we announced the hackathon a week in advance, giving people a bit more time to prepare their projects.

Wasp Betathon Homepage
Our dedicated hackathon landing page w/ intro video & countdown timer

And just like last time, we kept the Hackathon rules simple: no categories, no constraints, just 10 days to create any fullstack web app using Wasp, alone or in a team of up to 4 people.

Keyboard

We may be a bit unoriginal here, but we also decided to offer the same grand prize as the Betathon: a Wasp-colored mechanical keyboard. On top of that, runner-ups also got some project-related prizes, as well as Wasp beanies, shirts, and other swag. Of course, we also spotlight the winner’s on our social media accounts.

Something new we did this time was hold a post-hackathon presentation event on Discord, thanks to a suggestion made by Max, one of our most dedicated contributers. We gave each team a chance to present their projects and talk a bit about their experience. The turnout was great, with almost all the teams participating, and it helped us to get to know the faces behind the apps. Not only was this a great way to connect more with our community, but it also gave us some insight into where are users are coming from, what they're interested in, and what they're looking for in Wasp.

Promotion​

As of late, we've made an effort to promote exemplary apps built with Wasp, as well as create some of our own. This has been a great way to show off Wasp's capabilities, and has resulted in a noticeable increase in interest and traffic. Therefore, for the Hackathon, we let the organic interest in Wasp be the driver for the Hackathon, as we didn't do much promotion outside of our own channels, nor did we partner with any other sponsors this time. We simply announced the Hackathon and directed people to our Hacakthon homepage we created.

The hackathon page is nice to have as a central spot for all the rules and relevant info. We also added a fun intro video using AI-generated narration of a possibly well-known actor 😎. Overall, the effort put into the homepage gives participants the feeling that they’re entering into a serious contest and committing to something of substance, while the light-heartedness of the promotion material lets them know that it's more about fun than serious prizes. But even in the abscence of big winnings, the quality of the submissions were suprisingly high. Intrinsic motivation, ftw! 🤩

Hackathon Wasp app repo
Wanna host your own Hackathon? Use our template app!

Again, just like we did previously, we wrote the Hackathon Homepage with Wasp, and put the source code up on our GitHub. We thought it might inspire people to build with Wasp, using it as a guide while creating their own projects for the hackathon, plus it could be used by others in the future if they want to host their own hackathon. 💻

The Response 2.0​

We were really pleased to see the response to the Hackathon surpass our expectations, yet again. The number, quality, and creativity of the submissions were even better than the Betathon. We also had a lot of fun interacting with the participants, and we're looking forward to doing it again soon.

It's reaffirming to see Wasp grow along with our community, as they build more and more cool stuff with it. Events like this give us a morale and confidence boost as it confirms that we're building something the community wants.

Thanks so much again to the participants for their hard work and contributions. We're grateful and happy to have you along for the ride! 🐝🚀

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Hackathon #2: Results & Review

· 6 min read
Vinny

To finalize Wasp's Launch Week #2, we held our second Hackathon. Just like the "Betathon" before it, it was an open hackathon where the only requirement was to build something cool with Wasp!

In this post, I’ll give a quick overview of:

  • the hackathon results 🏆
  • how the hackathon was organized
  • how we promoted it
  • the community response

…and the Winners Are:​

What’s a hackathon without the participants!? Let’s get this post off to a proper start by congratulating our winners and showcasing their work. 🔍

🥇 Typergotchi​

Typergotchi

Our unofficial mascot, Da Boi, makes his debut app appearance in this fun, feature-rich typing game!

“Wasp makes building fullstack apps fast and fun. We've done lots of hackthons in the past, and we couldn't pass up the chance to win a mechanical keyboard :)” - Umbrien & kg04ls

🥈 Office Wars​

Office Wars

A turn-based, multi-player strategy game where you command your tank across a hexagonal map. A great way to keep your coworkers engaged while you wait for your code to compile!

“We love how Wasp brings the tools that are already being used by developers under the same umbrella. It's very streamlined and makes building fullstack apps easy to accomplish... like django but w/ more superpowers” - Roland & Luís

🥉 Tied for Third: Bee Pretty & StorAI​

Bee Pretty

StorAI

After 5 minutes of working with Wasp I thought, this is phenomenal! So much just works out of the box -- everything was flawless" - mkinkela1

🥳 And A Big Round of Applause for the Rest of the Participants!​

Thanks so much to rest of the participants:

  • Max for submitting Feedback Hub, which we award "the most SaaS-y app".
  • Richard for submitting Promise, for winning the "best last-minute minimal-effort submission" award.
  • Swarnavo for submitting his Dashboard Panel app.

Hackathon How-to​

For our first hackathon, the "Betathon", we announced and started it on the final day of our launch week. Looking back, this probably wasn't the best approach because it didn't give people much time to prepare. This time around, we announced the hackathon a week in advance, giving people a bit more time to prepare their projects.

Wasp Betathon Homepage
Our dedicated hackathon landing page w/ intro video & countdown timer

And just like last time, we kept the Hackathon rules simple: no categories, no constraints, just 10 days to create any fullstack web app using Wasp, alone or in a team of up to 4 people.

Keyboard

We may be a bit unoriginal here, but we also decided to offer the same grand prize as the Betathon: a Wasp-colored mechanical keyboard. On top of that, runner-ups also got some project-related prizes, as well as Wasp beanies, shirts, and other swag. Of course, we also spotlight the winner’s on our social media accounts.

Something new we did this time was hold a post-hackathon presentation event on Discord, thanks to a suggestion made by Max, one of our most dedicated contributers. We gave each team a chance to present their projects and talk a bit about their experience. The turnout was great, with almost all the teams participating, and it helped us to get to know the faces behind the apps. Not only was this a great way to connect more with our community, but it also gave us some insight into where are users are coming from, what they're interested in, and what they're looking for in Wasp.

Promotion​

As of late, we've made an effort to promote exemplary apps built with Wasp, as well as create some of our own. This has been a great way to show off Wasp's capabilities, and has resulted in a noticeable increase in interest and traffic. Therefore, for the Hackathon, we let the organic interest in Wasp be the driver for the Hackathon, as we didn't do much promotion outside of our own channels, nor did we partner with any other sponsors this time. We simply announced the Hackathon and directed people to our Hacakthon homepage we created.

The hackathon page is nice to have as a central spot for all the rules and relevant info. We also added a fun intro video using AI-generated narration of a possibly well-known actor 😎. Overall, the effort put into the homepage gives participants the feeling that they’re entering into a serious contest and committing to something of substance, while the light-heartedness of the promotion material lets them know that it's more about fun than serious prizes. But even in the abscence of big winnings, the quality of the submissions were suprisingly high. Intrinsic motivation, ftw! 🤩

Hackathon Wasp app repo
Wanna host your own Hackathon? Use our template app!

Again, just like we did previously, we wrote the Hackathon Homepage with Wasp, and put the source code up on our GitHub. We thought it might inspire people to build with Wasp, using it as a guide while creating their own projects for the hackathon, plus it could be used by others in the future if they want to host their own hackathon. 💻

The Response 2.0​

We were really pleased to see the response to the Hackathon surpass our expectations, yet again. The number, quality, and creativity of the submissions were even better than the Betathon. We also had a lot of fun interacting with the participants, and we're looking forward to doing it again soon.

It's reaffirming to see Wasp grow along with our community, as they build more and more cool stuff with it. Events like this give us a morale and confidence boost as it confirms that we're building something the community wants.

Thanks so much again to the participants for their hard work and contributions. We're grateful and happy to have you along for the ride! 🐝🚀

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/06/07/wasp-beta-update-may-23.html b/blog/2023/06/07/wasp-beta-update-may-23.html index 578bf53d54..be6e92c230 100644 --- a/blog/2023/06/07/wasp-beta-update-may-23.html +++ b/blog/2023/06/07/wasp-beta-update-may-23.html @@ -19,14 +19,14 @@ - - + + -
-

Wasp Beta - May 2023

· 6 min read
Matija Sosic

Wasp Update May 23

Want to stay in the loop? → Join our newsletter!

Hola Waspeteers 🐝,

What did one plant say to the other? Aloe! Long thyme no see. 🌱

Now that we've set the tone, let me guide you through what's new in Waspworld (that would be a cool theme park, right?):

Wasp Hackathon 2.0 is over - congrats to the winners! 🐝 🏆 🐝​

Congrats to the hackathon winners!
Shoutout to the winning team - Typergotchi! They even made a cool illustration with our mascot, Da Boi 🐝 😎

We had more submissions than ever, and the quality and creativity of your apps were really at the next level. We had everything from admin dashboards and GPT-powered story-telling apps to the actual games.

Hackathon testimonial

See all the winners and read a full Hackathon 2.0 review 👉 here 👈.

Wasp Launch Week #3 is in the making - get ready for the Magic 🔮 🧙​

As it always happens in the wilderness, after one launch week, there comes another one. And who are we to defy the laws of nature - thus, get ready for Launch Week #3!

We are aiming for the end of June, but we'll announce the exact date soon. Make sure to follow us on Twitter or/and join our Discord to stay in the loop.

Beautiful
When you see it ✨

After Pizzazz 🍕 ...​

As you might remember, the motto/topic of our last launch was Pizzaz, which referred to improving the developer experience in Wasp - full-stack auth, one-line deployment, type safety, db tooling, ...

... Comes Magic! 🔮​

While DX will always be our top priority, we're now shifting gears a bit - the keyword we chose to represent our next launch is ✨ Magic ✨. The reason is that now that we have a majority of the features you'd expect in a web framework in place, we can start utilizing Wasp's unique compiler-driven approach to offer next-level features no other framework can!

LW3 Sneak Peek 🤫 👀​

More details coming soon, but in the meanwhile, here are some of the features we're most excited about:

🚧 Wasp AI 🤖 ✨​

There is no mAgIc without AI! We cannot share many details on this yet, but it is something we've been exploring a lot lately. Our previous experiments have shown that, due to its declarative and human-readable nature, Wasp is naturally a very good fit for LLMs.

We'll take this to the next level for our next launch - stay tuned!

🚧 Auto CRUD​

Although Wasp helps a lot with bootstrapping your app, one repetitive thing that you have to do every time is implement "standard" CRUD operations for your data models.

We decided to put a stop to it - welcome our new (incoming) feature, Auto CRUD!

Auto CRUD
Syntax proposal for the new Auto CRUD feature

All you have to do is specify in your .wasp file which CRUD operations you want, and they will be auto-generated for you to use in your JS/TS code. The best part is when you update your data model, these will get updated as well! 🤯

This feature is also a really good showcase of Wasp's compiler muscles - the best you could get with a traditional framework approach is scaffolding, which means spitting out code that will quickly get outdated and that you have to maintain.

See a 2-min demo of Wasp Auto CRUD in action - by our founding engineer Miho

Showing off compiler muscles
Our compiler right now

🚧 Advanced syntax completion for .wasp files (LSP)​

Improved LSP

We're making our VS Code extension even better! So far it has provided highlighting and auto-completion for top-level declarations (e.g., route, entity, query, ...), but now it's going even deeper. Every property will display its full type as you are typing it out + you'll get a context-aware auto-completion.

🚧 Support for web sockets 🔌 🧦!​

Wasp will soon support Web Sockets! This will allow you to have a persistent, real-time connection between your client and server, which is great for chat apps, games, and more.

Web sockets in Wasp
Defining a new web socket in Wasp config file

For now it is a stand-alone feature, but it opens some really interesting possibilities - e.g. combining this with Wasp's query/action system and letting you declare a particular query to be "live". Just an idea for now but something to keep in mind as we test and receive more feedback on this feature.

From the blog 📖​

The community buzz 🐝 💬​

Last month was super buzzy! We got several awesome reviews, and Wasp also got picked up by a couple of YouTube dev influencers:

Wasp testimonial

Wasp GitHub Star Growth - 2,825 ⭐​

Getting close to the big 3,000! Huge thanks to all our contributors and stargazers - you are amazing!

GitHub stars - almost 3,000!
Almost 3,000 stars! 🐝 🚀

And if you haven't yet, please star us on Github! Yes, we are shameless star beggars, but if you believe in the project and want to support it that's one of the best ways to do it (next to actually building something with Wasp - go do that too! :D)

That's a wrap! 🌯​

A dramatic goodbye gif
A dramatic goodbye - don't ever let go

That's it for this month and thanks for reading! Since you've come this far, you deserve one final treat - a Wasp-themed joke generated by ChatGPT:

GPT Wasp joke
Good one, dad.

Fly high, and we'll see you soon 🐝 🐝,
+

+

Wasp Beta - May 2023

· 6 min read
Matija Sosic

Wasp Update May 23

Want to stay in the loop? → Join our newsletter!

Hola Waspeteers 🐝,

What did one plant say to the other? Aloe! Long thyme no see. 🌱

Now that we've set the tone, let me guide you through what's new in Waspworld (that would be a cool theme park, right?):

Wasp Hackathon 2.0 is over - congrats to the winners! 🐝 🏆 🐝​

Congrats to the hackathon winners!
Shoutout to the winning team - Typergotchi! They even made a cool illustration with our mascot, Da Boi 🐝 😎

We had more submissions than ever, and the quality and creativity of your apps were really at the next level. We had everything from admin dashboards and GPT-powered story-telling apps to the actual games.

Hackathon testimonial

See all the winners and read a full Hackathon 2.0 review 👉 here 👈.

Wasp Launch Week #3 is in the making - get ready for the Magic 🔮 🧙​

As it always happens in the wilderness, after one launch week, there comes another one. And who are we to defy the laws of nature - thus, get ready for Launch Week #3!

We are aiming for the end of June, but we'll announce the exact date soon. Make sure to follow us on Twitter or/and join our Discord to stay in the loop.

Beautiful
When you see it ✨

After Pizzazz 🍕 ...​

As you might remember, the motto/topic of our last launch was Pizzaz, which referred to improving the developer experience in Wasp - full-stack auth, one-line deployment, type safety, db tooling, ...

... Comes Magic! 🔮​

While DX will always be our top priority, we're now shifting gears a bit - the keyword we chose to represent our next launch is ✨ Magic ✨. The reason is that now that we have a majority of the features you'd expect in a web framework in place, we can start utilizing Wasp's unique compiler-driven approach to offer next-level features no other framework can!

LW3 Sneak Peek 🤫 👀​

More details coming soon, but in the meanwhile, here are some of the features we're most excited about:

🚧 Wasp AI 🤖 ✨​

There is no mAgIc without AI! We cannot share many details on this yet, but it is something we've been exploring a lot lately. Our previous experiments have shown that, due to its declarative and human-readable nature, Wasp is naturally a very good fit for LLMs.

We'll take this to the next level for our next launch - stay tuned!

🚧 Auto CRUD​

Although Wasp helps a lot with bootstrapping your app, one repetitive thing that you have to do every time is implement "standard" CRUD operations for your data models.

We decided to put a stop to it - welcome our new (incoming) feature, Auto CRUD!

Auto CRUD
Syntax proposal for the new Auto CRUD feature

All you have to do is specify in your .wasp file which CRUD operations you want, and they will be auto-generated for you to use in your JS/TS code. The best part is when you update your data model, these will get updated as well! 🤯

This feature is also a really good showcase of Wasp's compiler muscles - the best you could get with a traditional framework approach is scaffolding, which means spitting out code that will quickly get outdated and that you have to maintain.

See a 2-min demo of Wasp Auto CRUD in action - by our founding engineer Miho

Showing off compiler muscles
Our compiler right now

🚧 Advanced syntax completion for .wasp files (LSP)​

Improved LSP

We're making our VS Code extension even better! So far it has provided highlighting and auto-completion for top-level declarations (e.g., route, entity, query, ...), but now it's going even deeper. Every property will display its full type as you are typing it out + you'll get a context-aware auto-completion.

🚧 Support for web sockets 🔌 🧦!​

Wasp will soon support Web Sockets! This will allow you to have a persistent, real-time connection between your client and server, which is great for chat apps, games, and more.

Web sockets in Wasp
Defining a new web socket in Wasp config file

For now it is a stand-alone feature, but it opens some really interesting possibilities - e.g. combining this with Wasp's query/action system and letting you declare a particular query to be "live". Just an idea for now but something to keep in mind as we test and receive more feedback on this feature.

From the blog 📖​

The community buzz 🐝 💬​

Last month was super buzzy! We got several awesome reviews, and Wasp also got picked up by a couple of YouTube dev influencers:

Wasp testimonial

Wasp GitHub Star Growth - 2,825 ⭐​

Getting close to the big 3,000! Huge thanks to all our contributors and stargazers - you are amazing!

GitHub stars - almost 3,000!
Almost 3,000 stars! 🐝 🚀

And if you haven't yet, please star us on Github! Yes, we are shameless star beggars, but if you believe in the project and want to support it that's one of the best ways to do it (next to actually building something with Wasp - go do that too! :D)

That's a wrap! 🌯​

A dramatic goodbye gif
A dramatic goodbye - don't ever let go

That's it for this month and thanks for reading! Since you've come this far, you deserve one final treat - a Wasp-themed joke generated by ChatGPT:

GPT Wasp joke
Good one, dad.

Fly high, and we'll see you soon 🐝 🐝,
Matija, Martin and the Wasp team

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - + + \ No newline at end of file diff --git a/blog/2023/06/22/wasp-launch-week-three.html b/blog/2023/06/22/wasp-launch-week-three.html index a1d62bb6f6..01af4896d0 100644 --- a/blog/2023/06/22/wasp-launch-week-three.html +++ b/blog/2023/06/22/wasp-launch-week-three.html @@ -19,13 +19,13 @@ - - + + -
-

Wasp Launch Week #3: Magic

· 6 min read
Matija Sosic

Launch Week 3 is coming

By now, it is a tradition. For the every upcoming launch week, we ask ourselves how can we top the last one? How can we make building full-stack web apps easier, more enjoyable and get rid of even more boilerplate?

If this is the first time you're joining, check our previous launches:

Our first launch week was about making the promise of Wasp Alpha a reality, so you can build what you envisioned and deploy your app to production. The second launch made the whole experience much more polished, getting closer to the DX you'd expect from a mature web framework.

Why Magic?​

For this launch, with all the basics in place and you having built thousands of apps with Wasp (thank you!), we started pushing the boundaries of what web frameworks can do, utilising Wasp's unique DSL/compiler approach. This is still barely scratching the surface, but you'll be able to try it out yourself and get a taste of what the future of web development will look like.

Magic - LW3 in a nutshell
This launch week in a nutshell.

What's coming 🐝​

Every day next week, starting Monday, June 26, we'll highlight a major new feature in Wasp. We'll update this post daily as we reveal each feature, so make sure to keep coming back! Follow us on twitter (@wasplang) to stay in the loop and also join our Discord to join the community and get help as you're trying Wasp out.

Launch party 🚀🎉​

launch event 2 - screenshot
A bit of the atmosphere from our last launch party

What would a launch be without a proper event and a party? A boring, heartless event, that's what!

That's why we'll get together to celebrate the launch, our community (you!) and all the hard work that's been put into this new, fresh edition of Wasp. You will also get to meet the team and hear first-hand from the makers about the latest features and plans for the future.

The party starts at 9.30 am EDT / 3.30 pm CET - sign up here and make sure to mark yourself as "interested"!

launch event - how to join

As per usual, there will be memes, swag and lots of interesting dev discussions!

Auto CRUD | Monday: The future is now 🛸​

The future is now

We'll immediately kick things off with a bang! What's the one thing that all developers universally agree is something they'd like to do less of? Writing boilerplate CRUD logic, of course! Yet, it's 2023 and the best we managed to do is get an AI write it half-correctly for us and we still have to maintain it.

That's what we are coming after - is it possible to avoid writing (or generating) CRUD code in the first place? How far can we take it and what's then even left for your to code? Join us on Monday and find out!

When: Monday, June 26 2023

Read more about it:

WebSocket Support | Tuesday: Be real, time 🔌⏱​

Realtime

Sometimes, you just want to keep it real. Especially when you are dealing with time. I've been dropping some hints here - have you figured out what is this about? If yes, drop us a line on twitter (@wasplang) and the first one to get it right will get a special (real and timely) award!

Another situation where you might want to keep things real is when chatting to someone, especially via the text (wink wink hint hint 🧦).

When: Tuesday, June 27 2023

Read more about it:

Wednesday: Community Day 🤗​

Community
Just let it all out

Community is at the centre of Wasp, and Wednesday is at the centre of the week, so it's only appropriate to marry the two together. We'll spotlight the amazing OSS tools Wasp is built on top of and also you - all the cool stuff you have built with Wasp and how you're contributing every day to make our community better!

When: Wednesday, June 28 2023

Read more about it: What can you build with Wasp?

Wasp LSP 2.0 | Thursday: Take care of your tools 🛠​

Tools

It's a well known fact that a developer is only as good as the tools they are using. That actually applies to anybody - if Gimli hadn't spent time sharpening his axe, he wouldn't stand a chance against these orcs, would he?

Us at Wasp, we are pretty much the same as Gimli - we take our tools seriously. As we are innovating on the framework features, our goal is to do the same with the tooling you use with Wasp. Get ready to get your hands dirty (with code).

When: Thursday, June 29 2023

Read more about it: A blog post introing Wasp LSP 2.0

GPT Web App Generator | Friday: Waspularity 🤖 + Tutorial-o-thon!​

Waspularity

For the final day of the launch week, we have a really cool surprise for you. I'll just say it's something like Matrix but the robots are your friends and there's no that weird guy with sunglasses to ruin everything. And there might be cake.

To wrap the week up, we'll also start another hackathon, but this time in a bit different format. Since the best way to learn something is to teach it to others, we'll focus on tutorials this time! May the best tutorial win - more info coming soon.

When: Friday, June 30 2023

Read more about it:

Recap​

  • We are kicking off Launch Week #3 on Mon, June 26, at 9.30am EDT / 3.30pm CET - make sure to register for the event!
  • Launch Week #3 brings a ton of new exciting features - we’ll highlight one each day, starting Monday. Follow us on twitter and join our Discord to stay in the loop!
  • Following launch week, we’ll announce a tutorial-o-thon - get your writing gear ready!
Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Wasp Launch Week #3: Magic

· 6 min read
Matija Sosic

Launch Week 3 is coming

By now, it is a tradition. For the every upcoming launch week, we ask ourselves how can we top the last one? How can we make building full-stack web apps easier, more enjoyable and get rid of even more boilerplate?

If this is the first time you're joining, check our previous launches:

Our first launch week was about making the promise of Wasp Alpha a reality, so you can build what you envisioned and deploy your app to production. The second launch made the whole experience much more polished, getting closer to the DX you'd expect from a mature web framework.

Why Magic?​

For this launch, with all the basics in place and you having built thousands of apps with Wasp (thank you!), we started pushing the boundaries of what web frameworks can do, utilising Wasp's unique DSL/compiler approach. This is still barely scratching the surface, but you'll be able to try it out yourself and get a taste of what the future of web development will look like.

Magic - LW3 in a nutshell
This launch week in a nutshell.

What's coming 🐝​

Every day next week, starting Monday, June 26, we'll highlight a major new feature in Wasp. We'll update this post daily as we reveal each feature, so make sure to keep coming back! Follow us on twitter (@wasplang) to stay in the loop and also join our Discord to join the community and get help as you're trying Wasp out.

Launch party 🚀🎉​

launch event 2 - screenshot
A bit of the atmosphere from our last launch party

What would a launch be without a proper event and a party? A boring, heartless event, that's what!

That's why we'll get together to celebrate the launch, our community (you!) and all the hard work that's been put into this new, fresh edition of Wasp. You will also get to meet the team and hear first-hand from the makers about the latest features and plans for the future.

The party starts at 9.30 am EDT / 3.30 pm CET - sign up here and make sure to mark yourself as "interested"!

launch event - how to join

As per usual, there will be memes, swag and lots of interesting dev discussions!

Auto CRUD | Monday: The future is now 🛸​

The future is now

We'll immediately kick things off with a bang! What's the one thing that all developers universally agree is something they'd like to do less of? Writing boilerplate CRUD logic, of course! Yet, it's 2023 and the best we managed to do is get an AI write it half-correctly for us and we still have to maintain it.

That's what we are coming after - is it possible to avoid writing (or generating) CRUD code in the first place? How far can we take it and what's then even left for your to code? Join us on Monday and find out!

When: Monday, June 26 2023

Read more about it:

WebSocket Support | Tuesday: Be real, time 🔌⏱​

Realtime

Sometimes, you just want to keep it real. Especially when you are dealing with time. I've been dropping some hints here - have you figured out what is this about? If yes, drop us a line on twitter (@wasplang) and the first one to get it right will get a special (real and timely) award!

Another situation where you might want to keep things real is when chatting to someone, especially via the text (wink wink hint hint 🧦).

When: Tuesday, June 27 2023

Read more about it:

Wednesday: Community Day 🤗​

Community
Just let it all out

Community is at the centre of Wasp, and Wednesday is at the centre of the week, so it's only appropriate to marry the two together. We'll spotlight the amazing OSS tools Wasp is built on top of and also you - all the cool stuff you have built with Wasp and how you're contributing every day to make our community better!

When: Wednesday, June 28 2023

Read more about it: What can you build with Wasp?

Wasp LSP 2.0 | Thursday: Take care of your tools 🛠​

Tools

It's a well known fact that a developer is only as good as the tools they are using. That actually applies to anybody - if Gimli hadn't spent time sharpening his axe, he wouldn't stand a chance against these orcs, would he?

Us at Wasp, we are pretty much the same as Gimli - we take our tools seriously. As we are innovating on the framework features, our goal is to do the same with the tooling you use with Wasp. Get ready to get your hands dirty (with code).

When: Thursday, June 29 2023

Read more about it: A blog post introing Wasp LSP 2.0

GPT Web App Generator | Friday: Waspularity 🤖 + Tutorial-o-thon!​

Waspularity

For the final day of the launch week, we have a really cool surprise for you. I'll just say it's something like Matrix but the robots are your friends and there's no that weird guy with sunglasses to ruin everything. And there might be cake.

To wrap the week up, we'll also start another hackathon, but this time in a bit different format. Since the best way to learn something is to teach it to others, we'll focus on tutorials this time! May the best tutorial win - more info coming soon.

When: Friday, June 30 2023

Read more about it:

Recap​

  • We are kicking off Launch Week #3 on Mon, June 26, at 9.30am EDT / 3.30pm CET - make sure to register for the event!
  • Launch Week #3 brings a ton of new exciting features - we’ll highlight one each day, starting Monday. Follow us on twitter and join our Discord to stay in the loop!
  • Following launch week, we’ll announce a tutorial-o-thon - get your writing gear ready!
Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/06/27/build-your-own-twitter-agent-langchain.html b/blog/2023/06/27/build-your-own-twitter-agent-langchain.html index e382b15bbc..391d7fd84e 100644 --- a/blog/2023/06/27/build-your-own-twitter-agent-langchain.html +++ b/blog/2023/06/27/build-your-own-twitter-agent-langchain.html @@ -19,13 +19,13 @@ - - + + -
-

Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

· 46 min read
Vinny

TL;DR​

LangChain, ChatGPT, and other emerging technology have made it possible to build some really creative tools.

In this tutorial, we’ll build a full-stack web app that acts as our own personal Twitter Agent, or “intern”, as I like to call it. It keeps track of your notes and ideas, and uses them — along with tweets from trending-setting twitter users — to brainstorm new ideas and write tweet drafts for you! 💥

BTW, If you get stuck during the tutorial, or at any point just want to check out the full, final repo of the app we're building, here it is: https://github.com/vincanger/twitter-intern

Before We Begin​

Wasp = } is the only open-source, completely serverful fullstack React/Node framework with a built in compiler that lets you build your app in a day and deploy with a single CLI command.

We’re working hard to help you build performant web apps as easily as possibly — including making these tutorials, which are released weekly!

We would be super grateful if you could help us out by starring our repo on GitHub: https://www.github.com/wasp-lang/wasp 🙏

https://media2.giphy.com/media/d0Pkp9OMIBdC0/giphy.gif?cid=7941fdc6b39mgj7h8orvi0f4bjebceyx4gj0ih1xb6s05ujc&ep=v1_gifs_search&rid=giphy.gif&ct=g

…even Ron would star Wasp on GitHub 🤩

Background​

Twitter is a great marketing tool. It’s also a great way to explore ideas and refine your own. But it can be time-consuming and difficult to maintain a tweeting habit.

https://media0.giphy.com/media/WSrR5xkvljaFMe7UPo/giphy.gif?cid=7941fdc6g9o3drj567dbwyuo1c66x76eq8awc2r1oop8oypl&ep=v1_gifs_search&rid=giphy.gif&ct=g

That’s why I decided to build my own personal twitter agent with LangChain on the basis of these assumptions:

🧠 LLMs (like ChatGPT) aren’t the best writers, but they ARE great at brainstorming new ideas.

📊 Certain twitter users drive the majority of discourse within certain niches, i.e. trend-setters influence what’s being discussed at the moment.

💡 the Agent needs context in order to generate ideas relevant to YOU and your opinions, so it should have access to your notes, ideas, tweets, etc.

So instead of trying to build a fully autonomous agent that does the tweeting for you, I thought it would be better to build an agent that does the BRAINSTORMING for you, based on your favorite trend-setting twitter users as well as your own ideas.

Imagine it like an intern that does the grunt work, while you do the curating!

https://media.giphy.com/media/26DNdV3b6dqn1jzR6/giphy.gif

In order to accomplish this, we need to take advantage of a few hot AI tools:

  • Embeddings and Vector Databases
  • LLMs (Large Language Models), such as ChatGPT
  • LangChain and sequential “chains” of LLM calls

Embeddings and Vector Databases give us a powerful way to perform similarity searches on our own notes and ideas.

If you’re not familiar with similarity search, the simplest way to describe what similarity search is by comparing it to a normal google search. In a normal search, the phrase “a mouse eats cheese” will return results with a combination of those words only. But a vector-based similarity search, on the other hand, would return those words, as well as results with related words such as “dog”, “cat”, “bone”, and “fish”.

You can see why that’s so powerful, because if we have non-exact but related notes, our similarity search will still return them!

https://media2.giphy.com/media/xUySTD7evBn33BMq3K/giphy.gif?cid=7941fdc6273if8qfk83gbnv8uabc4occ0tnyzk0g0gfh0qg5&ep=v1_gifs_search&rid=giphy.gif&ct=g

For example, if our favorite trend-setting twitter user makes a post about the benefits of typescript, but we only have a note on “our favorite React hooks”, our similarity search would still likely return such a result. And that’s huge!

Once we get those notes, we can pass them to the ChatGPT completion API along with a prompt to generate more ideas. The result from this prompt will then be sent to another prompt with instructions to generate a draft tweet. We save these sweet results to our Postgres relational database.

This “chain” of prompting is essentially where the LangChain package gets its name 🙂

The flow of information through the app

This approach will give us a wealth of new ideas and tweet drafts related to our favorite trend-setting twitter users’ tweets. We can look through these, edit and save our favorite ideas to our “notes” vector store, or maybe send off some tweets.

I’ve personally been using this app for a while now, and not only has it generated some great ideas, but it also helps to inspire new ones (even if some of the ideas it generates are “meh”), which is why I included an “Add Note” feature front and center to the nav bar

twitter-agent-add-note.png

Ok. Enough background. Let’s start building your own personal twitter intern! 🤖

BTW, if you get stuck at all while following the tutorial, you can always reference this tutorial’s repo, which has the finished app: Twitter Intern GitHub Repo

Configuration​

Set up your Wasp project​

We’re going to make this a full-stack React/NodeJS web app so we need to get that set up first. But don’t worry, it won’t take long AT ALL, because we will be using Wasp as the framework.

Wasp does all the heavy lifting for us. You’ll see what I mean in a second.

# First, install Wasp by running this in your terminal:

curl -sSL https://get.wasp-lang.dev/installer.sh | sh

# next, create a new project:

wasp new twitter-agent

# cd into the new directory and start the project:

cd twitter-agent && wasp start

Great! When running wasp start, Wasp will install all the necessary npm packages, start our server on port 3001, and our React client on port 3000. Head to localhost:3000 in your browser to check it out.

Untitled

Tip ℹ️

you can install the Wasp vscode extension for the best developer experience.

You’ll notice Wasp sets up your full-stack app with a file structure like so:

.
├── main.wasp             # The wasp config file.
└── src
    ├── client            # Your React client code (JS/CSS/HTML) goes here.
    ├── server            # Your server code (Node JS) goes here.
    └── shared            # Your shared (runtime independent) code goes here.

Let’s start adding some server-side code.

Server-Side & Database Entities​

Start by adding a .env.server file in the root directory of your project:

# https://platform.openai.com/account/api-keys
OPENAI_API_KEY=

# sign up for a free tier account at https://www.pinecone.io/
PINECONE_API_KEY=
# will be a location, e.g 'us-west4-gcp-free'
PINECONE_ENV=   

# We will fill these in later during the Twitter Scraping section
# Twitter details -- only needed once for Rettiwt.account.login() to get the tokens 
TWITTER_EMAIL=
TWITTER_HANDLE=
TWITTER_PASSWORD=

# TOKENS -- fill these in after running the getTwitterTokens script in the Twitter Scraping section
KDT=
TWID=
CT0=
AUTH_TOKEN=

We need a way for us to store all our great ideas. So let’s first head to Pinecone.io and set up a free trial account.

Untitled

In the Pinecone dashboard, go to API keys and create a new one. Copy and paste your Environment and API Key into .env.server

Do the same for OpenAI, by creating an account and key at https://platform.openai.com/account/api-keys

Now let’s replace the contents of the main.wasp config file, which is like the “skeleton” of your app, with the code below. This will configure most of the fullstack app for you 🤯

app twitterAgent {
  wasp: {
    version: "^0.10.6"
  },
  title: "twitter-agent",
    head: [
    "<script async src='https://platform.twitter.com/widgets.js' charset='utf-8'></script>"
  ],
  db: { 
    system: PostgreSQL,
  },
  auth: {
    userEntity: User,
    onAuthFailedRedirectTo: "/login",
    methods: {
      usernameAndPassword: {},
    }
  },
  dependencies: [
    ("openai", "3.2.1"),
    ("rettiwt-api", "1.1.8"),
    ("langchain", "0.0.91"),
    ("@pinecone-database/pinecone", "0.1.6"),
    ("@headlessui/react", "1.7.15"),
    ("react-icons", "4.8.0"),
        ("react-twitter-embed", "4.0.4")
  ],
}

// ### Database Models

entity Tweet {=psl
    id              Int           @id @default(autoincrement())
  tweetId         String        
  authorUsername  String
  content         String
  tweetedAt       DateTime      @default(now())
  user            User          @relation(fields: [userId], references: [id])
  userId          Int
  drafts          TweetDraft[]
  ideas           GeneratedIdea[]
psl=}

entity TweetDraft {=psl
  id              Int         @id @default(autoincrement())
  content         String
  notes           String
  originalTweet   Tweet       @relation(fields: [originalTweetId], references: [id])
  originalTweetId Int
  createdAt       DateTime    @default(now())
  user            User        @relation(fields: [userId], references: [id])
  userId          Int
psl=}

entity GeneratedIdea {=psl
  id              Int         @id @default(autoincrement())
  content         String
  createdAt       DateTime    @default(now())
  updatedAt       DateTime    @default(now())
  user            User        @relation(fields: [userId], references: [id])
  userId          Int
  originalTweet   Tweet?      @relation(fields: [originalTweetId], references: [id])
  originalTweetId Int?
  isEmbedded      Boolean     @default(false)
psl=}

entity User {=psl
  id              Int         @id @default(autoincrement())
  username        String      @unique
  password        String
  createdAt       DateTime    @default(now())
  favUsers        String[]
  originalTweets  Tweet[]
  tweetDrafts     TweetDraft[]
  generatedIdeas  GeneratedIdea[]
psl=}

// <<< Client Pages & Routes

route RootRoute { path: "/", to: MainPage }
page MainPage {
  authRequired: true,
  component: import Main from "@client/MainPage"
}

//...
note

You might have noticed this {=psl psl=} syntax in the entities above. This denotes that anything in between these psl brackets is actually a different language, in this case, Prisma Schema Language. Wasp uses Prisma under the hood, so if you've used Prisma before, it should be straightforward.

As you can see, our main.wasp config file has our:

  • dependencies,
  • authentication method,
  • database type, and
  • database models (”entities”)

With this, our app structure is mostly defined and Wasp will take care of a ton of configuration for us.

Database Setup​

But we still need to get a postgres database running. Usually this can be pretty annoying, but with Wasp, just have Docker Deskop installed and running, then open up another separate terminal tab/window and then run:

wasp start db

This will start and connect your app to a Postgres database for you. No need to do anything else! 🤯 Just leave this terminal tab, along with docker desktop, open and running in the background.

In a different terminal tab, run: 

wasp db migrate-dev

and make sure to give your database migration a name.

If you stopped the wasp dev server to run this command, go ahead and start it again with wasp start.

At this point, our app will be navigating us to localhost:3000/login but because we haven’t implemented a login screen/flow yet, we will be seeing a blank screen. Don’t worry, we’ll get to that.

Embedding Ideas & Notes​

Server Action​

First though, in the main.wasp config file, let’s define a server action for saving notes and ideas. Go ahead and add the code below to the bottom of the file:

// main.wasp

//...
// <<< Client Pages & Routes

route RootRoute { path: "/", to: MainPage }
page MainPage {
  authRequired: true,
  component: import Main from "@client/MainPage"
}

// !!! Actions

action embedIdea {
  fn: import { embedIdea } from "@server/ideas.js",
  entities: [GeneratedIdea]
}

With the action declared, let’s create it. Make a new file, .src/server/ideas.ts in and add the following code:

import type { EmbedIdea } from '@wasp/actions/types';
import type { GeneratedIdea } from '@wasp/entities';
import HttpError from '@wasp/core/HttpError.js';
import { PineconeStore } from 'langchain/vectorstores/pinecone';
import { Document } from 'langchain/document';
import { OpenAIEmbeddings } from 'langchain/embeddings/openai';
import { PineconeClient } from '@pinecone-database/pinecone';

const pinecone = new PineconeClient();
export const initPinecone = async () => {
  await pinecone.init({
    environment: process.env.PINECONE_ENV!,
    apiKey: process.env.PINECONE_API_KEY!,
  });
  return pinecone;
};

export const embeddings = new OpenAIEmbeddings({
  openAIApiKey: process.env.OPENAI_API_KEY,
});

/**
 * Embeds a single idea into the vector store
 */
export const embedIdea: EmbedIdea<{ idea: string }, GeneratedIdea> = async ({ idea }, context) => {
  if (!context.user) {
    throw new HttpError(401, 'User is not authorized');
  }

  console.log('idea: ', idea);

  try {
    let newIdea = await context.entities.GeneratedIdea.create({
        data: {
          content: idea,
          userId: context.user.id,
        },
      });
    

    if (!newIdea) {
      throw new HttpError(404, 'Idea not found');
    }

    const pinecone = await initPinecone();
        
    // we need to create an index to save the vector embeddings to
    // an index is similar to a table in relational database world
    const availableIndexes = await pinecone.listIndexes();
    if (!availableIndexes.includes('embeds-test')) {
      console.log('creating index');
      await pinecone.createIndex({
        createRequest: {
          name: 'embeds-test',
          // open ai uses 1536 dimensions for their embeddings
          dimension: 1536, 
        },
      });
    }

    const pineconeIndex = pinecone.Index('embeds-test');
        
    // the LangChain vectorStore wrapper
    const vectorStore = new PineconeStore(embeddings, {
      pineconeIndex: pineconeIndex,
      namespace: context.user.username,
    });
        
    // create a document with the idea's content to be embedded
    const ideaDoc = new Document({
      metadata: { type: 'note' },
      pageContent: newIdea.content,
    });
        
    // add the document to the vectore store along with its id
    await vectorStore.addDocuments([ideaDoc], [newIdea.id.toString()]);

    newIdea = await context.entities.GeneratedIdea.update({
      where: {
        id: newIdea.id,
      },
      data: {
        isEmbedded: true,
      },
    });
    console.log('idea embedded successfully!', newIdea);
    return newIdea;
  } catch (error: any) {
    throw new Error(error);
  }
};
info

We’ve defined the action function in our main.wasp file as coming from ‘@server/ideas.js’ but we’re creating an ideas.ts file. What's up with that?!

Well, Wasp internally uses esnext module resolution, which always requires specifying the extension as .js (i.e., the extension used in the emitted JS file). This applies to all @server imports (and files on the server in general). It does not apply to client files.

Great! Now we have a server action for adding notes and ideas to our vector database. And we didn’t even have to configure a server ourselves (thanks, Wasp 🙂).

Let's take a step back and walk through the code we just wrote though:

  1. We create a new Pinecone client and initialize it with our API key and environment.
  2. We create a new OpenAIEmbeddings client and initialize it with our OpenAI API key.
  3. We create a new index in our Pinecone database to store our vector embeddings.
  4. We create a new PineconeStore, which is a LangChain wrapper around our Pinecone client and our OpenAIEmbeddings client.
  5. We create a new Document with the idea’s content to be embedded.
  6. We add the document to the vector store along with its id.
  7. We also update the idea in our Postgres database to mark it as embedded.

Now we want to create the client-side functionality for adding ideas, but you’ll remember we defined an auth object in our wasp config file. So we’ll need to add the ability to log in before we do anything on the frontend.

Authentication​

Let’s add that quickly by adding a new a Route and Page definition to our main.wasp file

//...

route LoginPageRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import Login from "@client/LoginPage"
}

…and create the file src/client/LoginPage.tsx with the following content:

import { LoginForm } from '@wasp/auth/forms/Login';
import { SignupForm } from '@wasp/auth/forms/Signup';
import { useState } from 'react';

export default () => {
  const [showSignupForm, setShowSignupForm] = useState(false);

  const handleShowSignupForm = () => {
    setShowSignupForm((x) => !x);
  };

  return (
    <>
      {showSignupForm ? <SignupForm /> : <LoginForm />}
      <div onClick={handleShowSignupForm} className='underline cursor-pointer hover:opacity-80'>
        {showSignupForm ? 'Already Registered? Login!' : 'No Account? Sign up!'}
      </div>
    </>
  );
};
info

In the auth object on the main.wasp file, we used the usernameAndPassword method which is the simplest form of auth Wasp offers. If you’re interested, Wasp does provide abstractions for Google, Github, and Email Verified Authentication, but we will stick with the simplest auth for this tutorial.

With authentication all set up, if we try to go to localhost:3000 we will be automatically directed to the login/register form.

You’ll see that Wasp creates Login and Signup forms for us because of the auth object we defined in the main.wasp file. Sweet! 🎉

But even though we’ve added some style classes, we haven’t set up any css styling so it will probably be pretty ugly right about now.

🤢 Barf.

Untitled

Adding Tailwind CSS​

Luckily, Wasp comes with tailwind css support, so all we have to do to get that working is add the following files in the root directory of the project:

.
├── main.wasp            
├── src
│   ├── client            
│   ├── server           
│   └── shared            
├── postcss.config.cjs       # add this file here
├── tailwind.config.cjs      # and this here too
└── .wasproot

postcss.config.cjs

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

tailwind.config.cjs

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

Finally, replace the contents of your src/client/Main.css file with these lines:

@tailwind base;
@tailwind components;
@tailwind utilities;

Now we’ve got the magic of tailwind css on our sides! 🎨 We’ll get to styling later though. Patience, young grasshopper.

Adding Notes Client-side​

From here, let’s create the complimentary client-side components for adding notes to the vector store. Create a new .src/client/AddNote.tsx file with the following contents:

import { useState } from 'react';
import embedIdea from '@wasp/actions/embedIdea';

export default function AddNote() {
  const [idea, setIdea] = useState('');
  const [isIdeaEmbedding, setIsIdeaEmbedding] = useState(false);

  const handleEmbedIdea = async (e: any) => {
    try {
      setIsIdeaEmbedding(true);
      if (!idea) {
        throw new Error('Idea cannot be empty');
      }
      const embedIdeaResponse = await embedIdea({
        idea,
      });

      console.log('embedIdeaResponse: ', embedIdeaResponse);
    } catch (error: any) {
      alert(error.message);
    } finally {
      setIdea('');
      setIsIdeaEmbedding(false);
    }
  };

  return (
    <div className='flex flex-row gap-2 justify-center items-end w-full'>
      <textarea
        autoFocus
        onChange={(e) => setIdea(e.target.value)}
        value={idea}
        placeholder='LLMs are great for brainstorming!'
        className='w-full p-4 h-22 bg-neutral-100 border rounded-lg w-full'
      />
      <button
        onClick={handleEmbedIdea}
        className='flex flex-row justify-center items-center bg-neutral-100 hover:bg-neutral-200 border border-neutral-300 font-bold px-3 py-1 text-sm text-blue-500 whitespace-nowrap rounded-lg'
      >
        {isIdeaEmbedding ? 'Loading...' : 'Save Note'}
      </button>
    </div>
  );
}

Here we’re using the embedIdea action we defined earlier to add our idea to the vector store. We’re also using the useState hook to keep track of the idea we’re adding, as well as the loading state of the button.

So now we have a way to add our own ideas and notes to our vector store. Pretty sweet!

Generating New Ideas & Tweet Drafts​

Using LangChain's Sequential Chains​

Now we need to set up the sequential chain of LLM calls that LangChain is so great at.

Here are the steps we will take:

  1. define a function that uses LangChain to initiate a “chain” of API calls to OpenAI’s ChatGPT completions endpoint.
    1. this function takes a tweet that we pulled from one of our favorite twitter users as an argument, searches our vector store for similar notes & ideas, and returns a list of new “brainstormed” based on the example tweet and our notes.
  2. define a new action that loops through our favorite users array, pulls their most recent tweets, and sends them to our LangChain function mentioned above

So let’s start again by creating our LangChain function. Make a new src/server/chain.ts file:

import { ChatOpenAI } from 'langchain/chat_models/openai';
import { LLMChain, SequentialChain } from 'langchain/chains';
import { PromptTemplate } from 'langchain/prompts';
import { PineconeStore } from 'langchain/vectorstores/pinecone';
import { OpenAIEmbeddings } from 'langchain/embeddings/openai';
import { PineconeClient } from '@pinecone-database/pinecone';

const pinecone = new PineconeClient();
export const initPinecone = async () => {
  await pinecone.init({
    environment: process.env.PINECONE_ENV!,
    apiKey: process.env.PINECONE_API_KEY!,
  });
  return pinecone;
};

const embeddings = new OpenAIEmbeddings({
  openAIApiKey: process.env.OPENAI_API_KEY,
});

export const generateIdeas = async (exampleTweet: string, username: string) => {
  try {
    // remove quotes and curly braces as not to confuse langchain template parser
    exampleTweet = exampleTweet.replace(/"/g, '');
    exampleTweet = exampleTweet.replace(/{/g, '');
    exampleTweet = exampleTweet.replace(/}/g, '');

    const pinecone = await initPinecone();

    console.log('list indexes', await pinecone.listIndexes());

    // find the index we created earlier
    const pineconeIndex = pinecone.Index('embeds-test');

    const vectorStore = new PineconeStore(embeddings, {
      pineconeIndex: pineconeIndex,
      namespace: username,
    });

    //
    // sequential tweet chain begin --- >
    //
    /**
     * vector store results for notes similar to the original tweet
     */
    const searchRes = await vectorStore.similaritySearchWithScore(exampleTweet, 2);
    console.log('searchRes: ', searchRes);
    let notes = searchRes
      .filter((res) => res[1] > 0.7) // filter out strings that have less than %70 similarity
      .map((res) => res[0].pageContent)
      .join(' ');

    console.log('\n\n similarity search results of our notes-> ', notes);

        if (!notes || notes.length <= 2) {
      notes = exampleTweet;
    }

    const tweetLlm = new ChatOpenAI({
      openAIApiKey: process.env.OPENAI_API_KEY,
      temperature: 0.8, // 0 - 2 with 0 being more deterministic and 2 being most "loose". Past 1.3 the results tend to be more incoherent.
      modelName: 'gpt-3.5-turbo',
    });

    const tweetTemplate = `You are an expert idea generator. You will be given a user's notes and your goal is to use this information to brainstorm other novel ideas. 

      Notes: {notes}
    
      Ideas Brainstorm: 
      -`;

    const tweetPromptTemplate = new PromptTemplate({
      template: tweetTemplate,
      inputVariables: ['notes'],
    });

    const tweetChain = new LLMChain({
      llm: tweetLlm,
      prompt: tweetPromptTemplate,
      outputKey: 'newTweetIdeas',
    });

    const interestingTweetTemplate = `You are an expert interesting tweet generator. You will be given some tweet ideas and your goal is to choose one, and write a tweet based on it. Structure the tweet in an informal yet serious tone and do NOT include hashtags in the tweet!
 
      Tweet Ideas: {newTweetIdeas}
      
      Interesting Tweet:`;

    const interestingTweetLlm = new ChatOpenAI({
      openAIApiKey: process.env.OPENAI_API_KEY,
      temperature: 1.1,
      modelName: 'gpt-3.5-turbo',
    });

    const interestingTweetPrompt = new PromptTemplate({
      template: interestingTweetTemplate,
      inputVariables: ['newTweetIdeas'],
    });

    const interestingTweetChain = new LLMChain({
      llm: interestingTweetLlm,
      prompt: interestingTweetPrompt,
      outputKey: 'interestingTweet',
    });

    const overallChain = new SequentialChain({
      chains: [tweetChain, interestingTweetChain],
      inputVariables: ['notes'],
      outputVariables: ['newTweetIdeas', 'interestingTweet'],
      verbose: false,
    });

    type ChainDraftResponse = {
      newTweetIdeas: string;
      interestingTweet: string;
      notes: string;
    };

    const res1 = (await overallChain.call({
      notes,
    })) as ChainDraftResponse;

    return {
      ...res1,
      notes,
    };
  } catch (error: any) {
    throw new Error(error);
  }
};

Great! Let's run through the above code real quick:

  1. Initialize the Pinecone client
  2. Find our pinecone index (i.e. table) that we created earlier and initialize a new PineconeStore with LangChain
  3. Search our vector store for notes similar to the example tweet, filtering out any results that have less than %70 similarity
  4. Create a new ChatGPT completion chain that takes our notes as input and generates new tweet ideas
  5. Create a new ChatGPT completion chain that takes the new tweet ideas as input and generates a new tweet draft
  6. Create a new SequentialChain and combine the above two chains together so that we can pass it our notes as input and it returns the new tweet ideas and the new tweet draft as output
VECTOR COSINE SIMILARITY SCORES

A good similarity threshold for cosine similarity search on text strings depends on the specific application and the desired level of strictness in matching. Cosine similarity scores range between 0 and 1, with 0 meaning no similarity and 1 meaning completely identical text strings.

  • 0.8-0.9 = strict
  • 0.6-0.8 = moderate
  • 0.5 = relaxed.

In our case, we went for a moderate similarity threshold of 0.7, which means that we will only return notes that are at least 70% similar to the example tweet.

With this function, we will get our newTweetIdeas and our interestingTweet draft back as results that we can use within our server-side action.

Scraping Twitter​

Before we can pass an exampleTweet as an argument to our newly created Sequential Chain, we need to fetch it first!

To do this, we're going to use the Rettiwt-Api (which is just Twitter written backwards). Because it's an unofficial API there are a few caveats:

  1. We have to use the rettiwt client to login to our twitter account once. We will output the tokens it returns via a script and save those in our .env.server file for later.
  2. It's best to use an alternative account for this process. If you don't have an alternative account, go ahead and register a new one now.
⚠️

The use of an unofficial Twitter client, Rettiwt, is for illustrative purposes only. It's crucial that you familiarize yourself with Twitter's policies and rules regarding scraping before implementing these methods. Any abuse or misuse of these scripts and techniques may lead to actions taken against your Twitter account. We hold no responsibility for any consequences arising from your personal use of this tutorial and/or the related scripts. It is intended purely for learning and educational purposes.

Let's go ahead and create a new folder in src/server called scripts with a file inside called tokens.ts. This will be our script that we will run only once, just so that we get the necessary tokens to pass to our Rettiwt client.

We want to avoid running this script many times otherwise our account could get rate-limited. This shouldn't be an issue though, because once we return the tokens, they are valid for up to a year.

So inside src/server/scripts/tokens.ts add the following code:

import { Rettiwt } from 'rettiwt-api'; 

/**
 * This is a script we can now run from the cli with `wasp db seed`
 * IMPORTANT! We only want to run this script once, after which we save the tokens
 * in the .env.server file. They should be good for up to a year.
 */
export const getTwitterTokens = async () => {
  const tokens = await Rettiwt().account.login(
    process.env.TWITTER_EMAIL!,
    process.env.TWITTER_HANDLE!,
    process.env.TWITTER_PASSWORD!
  );

  console.log('tokens: ', tokens)
};

Make sure to add your twitter login details to our .env.server file, if you haven't already!

Great. To be able to run this script via a simple Wasp CLI command, add it via the seeds array within the db object at the top of your main.wasp file:

app twitterAgent {
  wasp: {
    version: "^0.10.6"
  },
  //...
  db: { 
    system: PostgreSQL,
    seeds: [ // <---------- add this
      import { getTwitterTokens } from "@server/scripts/tokens.js",
    ]
  },
  //...

Nice! Now for the fun part :)

in your terminal, at the root of your project, run wasp db seed, and you should see the tokens output to the terminal similar to this:

[Db]      Running seed: getTwitterTokens
[Db]      tokens:  { // your tokens... }

Copy and paste those tokens into your .env.server file:


# TOKENS -- fill these in after running the getTwitterTokens script in the Twitter Scraping section
KDT='...'
TWID='...'
CT0='...'
AUTH_TOKEN='...'

Now with that, we should be able to access our favorite trend-setting users' recent tweets and use them to help us brainstorm new ideas!

Server Action​

Ok, so we've got the tokens we need to get our trend-setting example tweets, and we've got a function that runs our similarity search and sequential chain of LLM calls.

Now let’s define an action in our main.wasp file that pulls it all together:

// actions...

action generateNewIdeas {
  fn: import { generateNewIdeas } from "@server/ideas.js",
  entities: [GeneratedIdea, Tweet, TweetDraft, User]
}

…and then create that action within src/server/ideas.ts


import type { 
    EmbedIdea,
    GenerateNewIdeas // < ---- add this type here -----
 } from '@wasp/actions/types';
// ... other imports ...
import { generateIdeas } from './chain.js'; // < ---- this too -----
import { Rettiwt } from 'rettiwt-api'; // < ---- and this here -----

const twitter = Rettiwt({ // < ---- and this -----
  kdt: process.env.KDT!,
  twid: process.env.TWID!,
  ct0:  process.env.CT0!,
  auth_token: process.env.AUTH_TOKEN!,
}); 

//... other stuff ...

export const generateNewIdeas: GenerateNewIdeas<unknown, void> = async (_args, context) => {
    try {
    // get the logged in user that Wasp passes to the action via the context
    const user = context.user

    if (!user) {
      throw new HttpError(401, 'User is not authorized');
    }

      for (let h = 0; h < user.favUsers.length; h++) {
        const favUser = user.favUsers[h];
        const oneDayFromNow = new Date(Date.now() + 24 * 60 * 60 * 1000);
        // convert oneDayFromNow to format YYYY-MM-DD
        const endDate = oneDayFromNow.toISOString().split('T')[0];

        // find the most recent tweet from the favUser
        const mostRecentTweet = await context.entities.Tweet.findFirst({
          where: {
            authorUsername: favUser,
          },
          orderBy: {
            tweetedAt: 'desc',
          },
        });

        console.log('mostRecentTweet: ', mostRecentTweet)

        const favUserTweets = await twitter.tweets.getTweets({
          fromUsers: [favUser],
          sinceId: mostRecentTweet?.tweetId || undefined, // get tweets since the most recent tweet if it exists
          endDate: endDate, // endDate in format YYYY-MM-DD
        });

        const favUserTweetTexts = favUserTweets.list

        for (let i = 0; i < favUserTweetTexts.length; i++) {
          const tweet = favUserTweetTexts[i];

          const existingTweet = await context.entities.User.findFirst({
            where: {
              id: user.id,
            },
            select: {
              originalTweets: {
                where: {
                  tweetId: tweet.id,
                },
              },
            },
          });

          /** 
           * If the tweet already exists in the database, skip generating drafts and ideas for it.
           */
          if (existingTweet) {
            console.log('tweet already exists in db, skipping generating drafts...');
            continue;
          }
          
          /**
           * this is where the magic happens
           */
          const draft = await generateIdeas(tweet.fullText, user.username);
          console.log('draft: ', draft);

          const originalTweet = await context.entities.Tweet.create({
            data: {
              tweetId: tweet.id,
              content: tweet.fullText,
              authorUsername: favUser,
              tweetedAt: new Date(tweet.createdAt),
              userId: user.id
            },
          });

          let newTweetIdeas = draft.newTweetIdeas.split('\n');
          newTweetIdeas = newTweetIdeas
            .filter((idea) => idea.trim().length > 0)
            .map((idea) => {
              // remove all dashes that are not directly followed by a letter
              idea = idea.replace(/-(?![a-zA-Z])/g, '');
              idea = idea.replace(/"/g, '');
              idea = idea.replace(/{/g, '');
              idea = idea.replace(/}/g, '');
              // remove hashtags and the words that follow them
              idea = idea.replace(/#[a-zA-Z0-9]+/g, '');
              idea = idea.replace(/^\s*[\r\n]/gm, ''); // remove new line breaks
              idea = idea.trim();
              // check if last character contains punctuation and if not add a period
              if (idea.length > 1 && !idea[idea.length - 1].match(/[.,\/#!$%\^&\*;:{}=\-_`~()]/g)) {
                idea += '.';
              }
              return idea;
            });
          for (let j = 0; j < newTweetIdeas.length; j++) {
            const newTweetIdea = newTweetIdeas[j];
            const newIdea = await context.entities.GeneratedIdea.create({
              data: {
                content: newTweetIdea,
                originalTweetId: originalTweet.id,
                userId: user.id
              },
            });
            console.log('newIdea saved to DB: ', newIdea);
          }

          const interestingTweetDraft = await context.entities.TweetDraft.create({
            data: {
              content: draft.interestingTweet,
              originalTweetId: originalTweet.id,
              notes: draft.notes,
              userId: user.id
            },
          });

          console.log('interestingTweetDraft saved to DB: ', interestingTweetDraft);

          // create a delay to avoid rate limiting
          await new Promise((resolve) => setTimeout(resolve, 1000));

        }
        await new Promise((resolve) => setTimeout(resolve, 1000));
      }

  } catch (error: any) {
    console.log('error', error);
    throw new HttpError(500, error);
  }
}

Ok! Nice work. There’s a lot going on above, so let’s just recap:

  • We loop through the array of our favorite users, as defined on our user entity in main.wasp,
  • Pull that user’s most recent tweets
  • Send that tweet to our generateIdeas function, which
    • searches our vector store for similar notes
    • asks GPT to generate similar, new ideas
    • sends those ideas in another prompt GPT to create a new, interesting tweet
    • returns the new ideas and interesting tweet
  • Create new GeneratedIdeas and a TweetDraft and saves them to our Postgres DB

Phew! We’re doing it 💪 

Fetching & Displaying Ideas​

Defining a Server-side Query​

Since we now have our chain of GPT prompts defined via LangChain and our server-side action, let’s go ahead and start implementing some front-end logic to fetch that data and display it to our users… which is basically only us at this point 🫂.

Just as we added a server-side action to generateNewIdeas we will now define a query to fetch those ideas.

Add the following query to your main.wasp file:

query getTweetDraftsWithIdeas {
  fn: import { getTweetDraftsWithIdeas } from "@server/ideas.js",
  entities: [TweetDraft]
}

In your src/server/ideas.ts file, below your generateNewIdeas action, add the query we just defined in our wasp file:

//... other imports ...
import type { GetTweetDraftsWithIdeas } from '@wasp/queries/types'; // <--- add this ---

// ... other functions ...

type TweetDraftsWithIdeas = {
  id: number;
  content: string;
  notes: string;
  createdAt: Date;
  originalTweet: {
    id: number;
    content: string;
    tweetId: string;
    tweetedAt: Date;
    ideas: GeneratedIdea[];
    authorUsername: string;
  };
}[];

export const getTweetDraftsWithIdeas: GetTweetDraftsWithIdeas<unknown, TweetDraftsWithIdeas> = async (_args, context) => {
  if (!context.user) {
    throw new HttpError(401, 'User is not authorized');
  }

  const drafts = await context.entities.TweetDraft.findMany({
    orderBy: {
      originalTweet: {
        tweetedAt: 'desc',
      }
    },
    where: {
      userId: context.user.id,
      createdAt: {
        gte: new Date(Date.now() - 2 * 24 * 60 * 60 * 1000), // Get drafts created within the last 2 days
      },
    },
    select: {
      id: true,
      content: true,
      notes: true,
      createdAt: true,
      originalTweet: {
        select: {
          id: true,
          tweetId: true,
          content: true,
          ideas: true,
          tweetedAt: true,
                    authorUsername: true,
        },
      },
    },
  });

  return drafts;
};

With this function we will be returning the tweet drafts we generate, along with our notes, the original tweet that inspired it, and the newly generated ideas.

Sweet!

Ok, but what good is a function that fetches the data if we’ve got nowhere to display it!?

Displaying Ideas Client-side​

Let’s go now to our src/client/MainPage.tsx file (make sure it’s got the .tsx extension and not .jsx) and replace the contents with these below:

import waspLogo from './waspLogo.png'
import './Main.css'

const MainPage = () => {
  return (
    <div className='min-h-screen bg-neutral-300/70 text-center'>
      <div className='flex flex-col justify-center items-center mx-auto pt-12'>
        <img src={waspLogo} className='w-5' />
      </div>
    </div>
  )
}
export default MainPage

At this point, you. might need to restart the wasp dev server running in your terminal to get the tailwind configuration to take effect (ctrl + c, then wasp start again).

You’ll now be prompted with the login / register screen. Go ahead and click on register and you will be automatically logged in and redirected to the main page, which at this point only has this:

Untitled

Let’s go back to our MainPage.tsx file and add the magic!

https://media3.giphy.com/media/ekv45izCuyXkXoHRaL/giphy.gif?cid=7941fdc6c3dszwj4xaoxg2kyj6xxdubjxn69m4qruhomhkut&ep=v1_gifs_search&rid=giphy.gif&ct=g

First, let’s create a buttons component so we don’t have to constantly style a new button. Create a new src/client/Button.tsx file:

import { ButtonHTMLAttributes } from 'react';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  isLoading?: boolean;
}

export default function Button({ isLoading, children, ...otherProps }: ButtonProps) {
  return (
    <button
      {...otherProps}
      className={`flex flex-row justify-center items-center bg-neutral-100 hover:bg-neutral-200 border border-neutral-300 text-blue-500 font-bold px-3 py-1 text-sm rounded-lg ${isLoading ? ' pointer-events-none opacity-70' : 'cursor-pointer'}`}
    >
      {isLoading? 'Loading...' : children}
    </button>
  );
}

Now let’s add it to your AddNote.tsx component, replacing the original button with this one. The whole file should look like this:

import { useState } from 'react';
import embedIdea from '@wasp/actions/embedIdea';
import Button from './Button';

export default function AddNote() {
  const [idea, setIdea] = useState('');
  const [isIdeaEmbedding, setIsIdeaEmbedding] = useState(false);

  const handleEmbedIdea = async (e: any) => {
    try {
      setIsIdeaEmbedding(true);
      if (!idea) {
        throw new Error('Idea cannot be empty');
      }
      const embedIdeaResponse = await embedIdea({
        idea,
      });

      console.log('embedIdeaResponse: ', embedIdeaResponse);
    } catch (error: any) {
      alert(error.message);
    } finally {
      setIdea('');
      setIsIdeaEmbedding(false);
    }
  };

  return (
    <div className='flex flex-row gap-2 justify-center items-end w-full'>
      <textarea
        autoFocus
        onChange={(e) => setIdea(e.target.value)}
        value={idea}
        placeholder='LLMs are great for brainstorming!'
        className='w-full p-4 h-22 bg-neutral-100 border rounded-lg w-full'
      />
      <Button isLoading={isIdeaEmbedding} onClick={handleEmbedIdea}>
        Save Note
      </Button>
    </div>
  );
}

Noice.

Next, we want our page to perform the following actions:

  1. create a button that runs our generateNewIdeas action when clicked
  2. define the query that fetches and caches the tweet drafts and ideas
  3. loop through the results and display them on the page

That’s exactly what the below code will do. Go ahead and replace the MainPage with it and take a minute to review what’s going on:

import waspLogo from './waspLogo.png';
import './Main.css';
import { useState } from 'react';
import generateNewIdeas from '@wasp/actions/generateNewIdeas';
import { useQuery } from '@wasp/queries';
import getTweetDraftsWithIdeas from '@wasp/queries/getTweetDraftsWithIdeas';
import AddNote from './AddNote';
import Button from './Button';

const MainPage = () => {
  const [isGenerating, setIsGenerating] = useState(false);

  const {
    data: tweetDrafts,
    isLoading: isTweetDraftsLoading,
    error: tweetDraftsError,
  } = useQuery(getTweetDraftsWithIdeas);

  const handleNewIdeas = async (e: any) => {
    try {
      setIsGenerating(true);
      await generateNewIdeas();
    } catch (error: any) {
      alert(error.message);
    } finally {
      setIsGenerating(false);
    }
  };

  if (isTweetDraftsLoading) {
    return 'Loading...';
  }

  if (tweetDraftsError) {
    return 'Error: ' + tweetDraftsError.message;
  }

  return (
    <div className='min-h-screen bg-neutral-300/70 text-center'>
      <div className='flex flex-col gap-6 justify-center items-center mx-auto pt-12'>
        <img src={waspLogo} className='w-5' />
        <div className='flex flex-col gap-4 justify-center items-center w-2/4'>
          <AddNote />
          <hr className='border border-t-1 border-neutral-100/70 w-full' />
          <div className='flex flex-row justify-center w-1/4'>
            <Button onClick={handleNewIdeas} isLoading={isGenerating}>
              Generate New Ideas
            </Button>
          </div>
          <div className='flex flex-col gap-4 justify-center items-center w-full'>
            {tweetDrafts.map((tweetDraft) => (
              <>
                <h2 className='text-2xl font-bold'>Generated Ideas</h2>
                <div key={tweetDraft.id} className='flex flex-col gap-2 justify-center items-center w-full'>
                  <h2>Tweet Draft</h2>
                  <div className='flex flex-row gap-2 justify-center items-center w-full'>
                    <div className='w-full p-4 h-22 bg-blue-100 border rounded-lg w-full'>{tweetDraft.content}</div>
                  </div>

                  {!!tweetDraft.notes && tweetDraft.notes !== tweetDraft.originalTweet.content && (
                    <>
                      <h2>Your Similar Notes</h2>
                      {tweetDraft.notes}
                    </>
                  )}
                  <div className='flex flex-col gap-2 justify-center items-center w-full'>
                    <h2>Ideas</h2>
                    {tweetDraft.originalTweet.ideas.map((idea) => (
                      <div key={idea.id} className='flex flex-row gap-2 justify-center items-center w-full'>
                        <div className='flex flex-row gap-2 justify-center items-center w-full'>
                          <div className='w-full p-4 h-22 bg-neutral-100 border rounded-lg w-full'>{idea.content}</div>
                        </div>
                      </div>
                    ))}
                  </div>
                </div>
              </>
            ))}
          </div>
        </div>
      </div>
    </div>
  );
};
export default MainPage;

This is what you should see on the homepage now! 🎉

Untitled

But, if you clicked ‘generate new ideas’ and nothing happened, well that’s because we haven’t defined any favorite trend-setting twitter users to scrape tweets from. And there’s no way to do that from the UI at the moment, so let’s open up the database manager and add some manually.

In a new terminal tab, in the root of your project, run:

wasp db studio

Then, in a new browswer tab, at localhost:5555 you should see your database.

Go to user, and you should be the only user in there. Add the usernames of a couple of your favorite trend-setting twitter users.

Untitled

Make sure the accounts have tweeted recently or your function won’t be able to scrape or generate anything!

Hey ✋

While you’re at it, if you’re liking this tutorial, give me a follow @hot_town for more future content like this

After adding the twitter usernames, make sure you click save 1 change.

Go back to your client and click the Generate New Ideas button again. This might take a while depending on how many tweets it’s generating ideas for, so be patient — and watch the console output in your terminal if you’re curious ;)

Untitled

Awesome! Now we should be getting back some generated ideas from our twitter “intern” which will help us brainstorm further notes and generate our own BANGER TWEETS.

But it would be cool to also display the tweet these ideas are referencing from the beginning. That way we’d have a bit more context on where the ideas came from.

Let’s do that then! In your MainPage file, at the very top, add the following import:

import { TwitterTweetEmbed } from 'react-twitter-embed';

This allows us to embed tweets with that nice twitter styling.

We already added this dependency to our main.wasp file at the beginning of the tutorial, so we can just import and start embedding tweets.

Let’s try it out now in our MainPage by adding the following snippet above our <h2>Tweet Draft</h2> element:

//...

<h2>Original Tweet</h2>
<div className='flex flex-row gap-2 justify-center items-center w-full'>
  <TwitterTweetEmbed tweetId={tweetDraft.originalTweet.tweetId} />
</div>

<h2>Tweet Draft</h2>
//...

Great. Now we should be sitting pretty 😻

Untitled

You might remember from the beginning of the tutorial when we defined the LLM calls, that if your vector store notes don’t turn back a cosine similarity of at least 0.7, your agent will generate its own ideas entirely without using your notes as a guide.

And since we have NO notes in our vector store at the moment, that’s exactly what it is doing. Which is fine, because we can let it brainstorm for us, and we can select our favorite notes and edit and add them as we see fit.

So you can go ahead and start adding notes whenever you feel like it 📝.

But, we’ve added our favorite twitter users to the database manually. It would be preferable to do it via an account settings page, right? Let’s make one then.

Creating an Account Settings Page​

First, add the route and page to your main.wasp config file, under the other routes:

//...

route AccountRoute { path: "/account", to: AccountPage }
page AccountPage {
  authRequired: true,
  component: import Account from "@client/AccountPage"
}

Next, let’s create a new page, src/client/AccountPage.tsx:

import Button from './Button';
import { ChangeEvent, useEffect, useState } from 'react';
import logout from '@wasp/auth/logout';
import type { User } from '@wasp/entities';

const AccountPage = ({ user }: { user: User }) => {
  return (
        <div className='flex flex-col justify-center items-center mt-12 w-full'>
      <div className='flex flex-col items-center justify-center gap-4 border border-neutral-700 bg-neutral-100/40 rounded-xl p-1 sm:p-4 w-full'>
        <div className='flex flex-row justify-end w-full px-4 pt-2'>
          <Button onClick={logout}>Logout</Button>
        </div>
        {JSON.stringify(user, null, 2)}
      </div>
    </div>
  );
};

export default AccountPage;

When you navigate to localhost:3000/account, you’ll notice two things, one of them being a logout button. You can see in our SettingsPage above that we imported a Wasp-provided logout function. We get this “for free” since we defined our auth strategy in the main.wasp file — a big time-saver!

Untitled

Because we also defined the AccountPage route with the authRequired: true property, Wasp will automatically pass the logged in user as a prop argument to our page. We can use the user object to display and update our favUsers, just as we can see in the image above.

To do that, let’s define a new updateAccount action in our main.wasp file:

action updateAccount {
  fn: import { updateAccount } from "@server/account.js",
  entities: [User]
}

Next, let’s create the updateAccount action in a new file, src/server/account.ts:

import type { UpdateAccount } from "@wasp/actions/types";
import HttpError from "@wasp/core/HttpError.js";

export const updateAccount: UpdateAccount<{ favUsers: string[] }, void> = async ({ favUsers }, context) => {
  if (!context.user) {
    throw new HttpError(401, "User is not authorized");
  }

  try {
    await context.entities.User.update({
      where: { id: context.user.id },
      data: { favUsers },
    });
    
  } catch (error: any) {
    throw new HttpError(500, error.message);
  }
}

Right. Now it’s time to put it all together in our Account page. We’re going to create a form for adding new twitter users to scrape tweets from, so at the bottom of your src/client/AccountPage.tsx, below your other code, add the following component:

function InputFields({ user }: { user: User }) {
  const [isLoading, setIsLoading] = useState(false);
  const [fields, setFields] = useState(['']);

  useEffect(() => {
    if (user?.favUsers.length > 0) {
      setFields(user.favUsers);
    }
  }, [user?.favUsers]);

  const handleAdd = () => {
    setFields([...fields, '']);
  };

  const handleRemove = () => {
    const newFields = [...fields];
    newFields.splice(fields.length - 1, 1);
    setFields(newFields);
  };

  const handleChange = (e: ChangeEvent<HTMLInputElement>, index: number) => {
    const newFields = [...fields];
    newFields[index] = e.target.value;
    setFields(newFields);
  };

  const handleSubmit = async () => {
    //...
  };

  return (
    <div className='w-full p-4'>
      <div className='flex flex-row justify-start items-start'>
        <h2 className='ml-1 font-bold'>Trend-Setting Twitter Accounts</h2>
      </div>
      {fields.map((field, index) => (
        <div key={index} className='my-2'>
          <input
            type='text'
            placeholder='Twitter Username'
            className='w-full bg-white border border-gray-300 rounded-lg py-2 px-4 text-gray-700 focus:border-blue-400 focus:outline-none'
            value={field}
            onChange={(e) => handleChange(e, index)}
          />
        </div>
      ))}
      <div className='my-2 flex flex-row justify-end gap-1'>
        {fields.length > 1 && <Button onClick={handleRemove}>-</Button>}
        {fields.length < 10 && (
          <Button onClick={handleAdd} className='bg-blue-500 text-white px-4 py-2 rounded'>
            +
          </Button>
        )}
      </div>
      <Button onClick={handleSubmit} isLoading={isLoading}>
        <span>Save</span>
      </Button>
    </div>
  );
}

This component takes care of adding the logged in user’s favUsers array to state, and displaying that in information in a set of input components.

The only thing missing from it is to add our updateAccount action we just defined earlier. So at the top of the file, let’s import it and add the logic to our InputFields submit handler

import updateAccount from '@wasp/actions/updateAccount'; // <--- add this import

//...

const handleSubmit = async () => { // < --- add this function
    try {
      setIsLoading(true);
      await updateAccount({ favUsers: fields });
    } catch (err: any) {
      alert(err.message);
    } finally {
      setIsLoading(false);
    }
  };

Also, in your AccountPage make sure to replace the line {JSON.stringify(user, null, 2)} with the newly created component <InputFields user={user} />.

Here is what the entire AccountPage.tsx file should now look like in case you get stuck:

import Button from './Button';
import { ChangeEvent, useEffect, useState } from 'react';
import logout from '@wasp/auth/logout';
import type { User } from '@wasp/entities';
import updateAccount from '@wasp/actions/updateAccount'

const AccountPage = ({ user }: { user: User }) => {
  return (
    <div className='flex flex-col justify-center items-center mt-12 w-full'>
      <div className='flex flex-col items-center justify-center gap-4 border border-neutral-700 bg-neutral-100/40 rounded-xl p-1 sm:p-4 w-full'>
        <div className='flex flex-row justify-end w-full px-4 pt-2'>
          <Button onClick={logout}>Logout</Button>
        </div>
        <InputFields user={user} />
      </div>
    </div>
  );
};

export default AccountPage;

function InputFields({ user }: { user: User }) {
  const [isLoading, setIsLoading] = useState(false);
  const [fields, setFields] = useState(['']);

  useEffect(() => {
    if (user?.favUsers.length > 0) {
      setFields(user.favUsers);
    }
  }, [user?.favUsers]);

  const handleAdd = () => {
    setFields([...fields, '']);
  };

  const handleRemove = () => {
    const newFields = [...fields];
    newFields.splice(fields.length - 1, 1);
    setFields(newFields);
  };

  const handleChange = (e: ChangeEvent<HTMLInputElement>, index: number) => {
    const newFields = [...fields];
    newFields[index] = e.target.value;
    setFields(newFields);
  };

  const handleSubmit = async () => {
    try {
      setIsLoading(true);
      await updateAccount({ favUsers: fields });
    } catch (err: any) {
      alert(err.message);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div className='w-full p-4'>
      <div className='flex flex-row justify-start items-start'>
        <h2 className='ml-1 font-bold'>Trend-Setting Twitter Accounts</h2>
      </div>
      {fields.map((field, index) => (
        <div key={index} className='my-2'>
          <input
            type='text'
            placeholder='Twitter Username'
            className='w-full bg-white border border-gray-300 rounded-lg py-2 px-4 text-gray-700 focus:border-blue-400 focus:outline-none'
            value={field}
            onChange={(e) => handleChange(e, index)}
          />
        </div>
      ))}
      <div className='my-2 flex flex-row justify-end gap-1'>
        {fields.length > 1 && <Button onClick={handleRemove}>-</Button>}
        {fields.length < 10 && (
          <Button onClick={handleAdd} className='bg-blue-500 text-white px-4 py-2 rounded'>
            +
          </Button>
        )}
      </div>
      <Button onClick={handleSubmit} isLoading={isLoading}>
        <span>Save</span>
      </Button>
    </div>
  );
}

And here’s what your AccountPage should look like when navigating to localhost:3000/account (note: the styling may be a bit ugly, but we’ll take care of that later):

Untitled

Fantastic. So we’ve got the majority of the app logic finished — our own personal twitter “intern” to help us all become thought leaders and thread bois 🤣.

Adding a Cron Job​

But wouldn’t it be cool if we could automate the Generate New Ideas process? Each time you click the button, it takes quite a while for tweets to be scraped, and ideas to be generated, especially if we are generating ideas for a lot of new tweets.

So it would be nicer if we had a cron job (recurring task), that ran automatically in the background at a set interval.

With Wasp, that’s also super easy to set up. To do so, let’s go to our main.wasp file and add our job at the very bottom:

//...

job newIdeasJob {
  executor: PgBoss,
  perform: {
    fn: import generateNewIdeasWorker from "@server/worker/generateNewIdeasWorker.js"
  },
  entities: [User, GeneratedIdea, Tweet, TweetDraft],
  schedule: {
    // run cron job every 30 minutes
    cron: "*/30 * * * *",
    executorOptions: {
      pgBoss: {=json { "retryLimit": 2 } json=},
    }
  }
}

Let’s run through the code above:

  • Jobs use pg-boss, a postgres extension, to queue and run tasks under the hood.
  • with perform we’re telling the job what function we want it to call: generateNewIdeasWorker
  • just like actions and queries, we have to tell the job which entities we want to give it access to. In this case, we will need access to all of our entities.
  • the schedule allows us to pass some options to pg-boss so that we can make it a recurring task. In this case, I set it to run every 30 minutes, but you can set it to any interval you’d like (tip: change the comment and let github co-pilot write the cron for you). We also tell pg-boss to retry a failed job two times.

Perfect. So now, our app will automatically scrape our favorite users’ tweets and generate new ideas for us every 30 minutes. This way, if we revisit the app after a few days, all the content will already be there and we won’t have to wait a long time for it to generate it for us. We also make sure we never miss out on generating ideas for older tweets.

But for that to happen, we have to define the function our job will call. To do this, create a new directory worker within the server folder, and within it a new file: src/server/worker/generateNewIdeasWorker

import { generateNewIdeas } from '../ideas.js';

export default async function generateNewIdeasWorker(_args: unknown, context: any) {
  try {
    console.log('Running recurring task: generateNewIdeasWorker')
    const allUsers = await context.entities.User.findMany({});

    for (const user of allUsers) {
      context.user = user;
      console.log('Generating new ideas for user: ', user.username);
      await generateNewIdeas(undefined as never, context);
      console.log('Done generating new ideas for user: ', user.username)
    }

  } catch (error: any) {
    console.log('Recurring task error: ', error);
  }
}

In this file, all we’re doing is looping through all the users in our database, and passing them via the context object to our generateNewIdeas action. The nice thing about jobs is that Wasp automatically passes the context object to these functions, which we can then pass along to our action.

So now, at the interval that you set (e.g. 30 minutes), you should notice the logs being printed to the console whenever your job starts automatically running.

[Server]  Generating new ideas for user:  vinny

Alright, things are looking pretty good now, but let’s not forget to add a page to view all the notes we added and embedded to our vector store!

Adding a Notes Page​

Go ahead and add the following route to your main.wasp file:

route NotesPage { path: "/notes", to: NotesPage }
page NotesPage {
  authRequired: true,
  component: import Notes from "@client/NotesPage"
}

Create the complementary page, src/client/NotesPage.tsx and add the following boilerplate just to get started (we’ll add the rest later):

const NotesPage = () => {

  return (
    <>Notes</>
  );
};

export default NotesPage;

It would be nice if we had a simple Nav Bar to navigate back and forth between our two pages. It would also be cool if we had our <AddNote /> input component on all pages, that way it’s easy for us to add an idea whenever inspiration strikes.

Rather than copying the NavBar and AddNote code to both pages, let’s create a wrapper, or “root”, component for our entire app so that all of our pages have the same Nav Bar and layout.

To do that, in our main.wasp file, let’s define our root component by adding a client property to our app configuration at the very top of the file. This is how the entire app object should look like now:

app twitterAgent {
  wasp: {
    version: "^0.10.6"
  },
  title: "twitter-agent",
  client: { 
    rootComponent: import App from "@client/App",
  },
  db: { 
    system: PostgreSQL,
  },
  auth: {
    userEntity: User,
    onAuthFailedRedirectTo: "/login",
    methods: {
      usernameAndPassword: {},
    }
  },
  dependencies: [
    ("openai", "3.2.1"),
    ("rettiwt-api", "1.1.8"),
    ("langchain", "0.0.91"),
    ("@pinecone-database/pinecone", "0.1.6"),
    ("@headlessui/react", "1.7.15"),
    ("react-icons", "4.8.0"),
    ("react-twitter-embed", "4.0.4")
  ],
}

// entities, operations, routes, and other stuff...

Next, create a new file src/client/App.tsx with the following content:

import './Main.css';
import AddNote from './AddNote';
import { ReactNode } from 'react';
import useAuth from '@wasp/auth/useAuth';

const App = ({ children }: { children: ReactNode }) => {

  const { data: user } = useAuth();

  return (
    <div className='min-h-screen bg-neutral-300/70 text-center'>
      <div className='flex flex-col gap-6 justify-center items-center mx-auto pt-12'>
        <div className='flex flex-row justify-between items-center w-1/2 mb-6 text-neutral-600 px-2'>
          <div className='flex justify-start w-1/3'>
            <a href='/' className='hover:underline cursor-pointer'>
              🤖 Generated Ideas
            </a>
          </div>
          <div className='flex justify-center w-1/3'>
            <a href='/notes' className='hover:underline cursor-pointer'>
              📝 My Notes
            </a>
          </div>
          <div className='flex justify-end w-1/3'>
            <a href='/account' className='hover:underline cursor-pointer'>
              👤 Account
            </a>
          </div>
        </div>

        <div className='flex flex-col gap-4 justify-center items-center w-2/4'>
          {!!user && <AddNote />}
          <hr className='border border-t-1 border-neutral-100/70 w-full' />
          {children}
        </div>
      </div>
    </div>
  );
};

export default App;

With this defined, Wasp will know to pass all other routes as children through our App component. That way, we will always show the Nav Bar and AddNote component on the top of every page.

We also take advantage of Wasp’s handy useAuth hook to check if a user is logged in, and if so we show the AddNote component.

Now, we can delete the duplicate code on our MainPage. This is what it should look like now:

import { useState } from 'react';
import generateNewIdeas from '@wasp/actions/generateNewIdeas';
import { useQuery } from '@wasp/queries';
import getTweetDraftsWithIdeas from '@wasp/queries/getTweetDraftsWithIdeas';
import Button from './Button';
import { TwitterTweetEmbed } from 'react-twitter-embed';

const MainPage = () => {
  const [isGenerating, setIsGenerating] = useState(false);

  const {
    data: tweetDrafts,
    isLoading: isTweetDraftsLoading,
    error: tweetDraftsError,
  } = useQuery(getTweetDraftsWithIdeas);

  const handleNewIdeas = async (e: any) => {
    try {
      setIsGenerating(true);
      await generateNewIdeas();
    } catch (error: any) {
      alert(error.message);
    } finally {
      setIsGenerating(false);
    }
  };

  if (isTweetDraftsLoading) {
    return 'Loading...';
  }

  if (tweetDraftsError) {
    return 'Error: ' + tweetDraftsError.message;
  }

  return (
    <>
      <div className='flex flex-row justify-center w-full'>
        <Button onClick={handleNewIdeas} isLoading={isGenerating}>
          Generate New Ideas
        </Button>
      </div>
      <div className='flex flex-col gap-4 justify-center items-center w-full'>
        {tweetDrafts.map((tweetDraft) => (
          <>
            <h2 className='text-2xl font-bold'>Generated Ideas</h2>
            <div key={tweetDraft.id} className='flex flex-col gap-2 justify-center items-center w-full'>
              <h2>Original Tweet</h2>
              <div className='flex flex-row gap-2 justify-center items-center w-full'>
                <TwitterTweetEmbed tweetId={tweetDraft.originalTweet.tweetId} />
              </div>
              <h2>Tweet Draft</h2>
              <div className='flex flex-row gap-2 justify-center items-center w-full'>
                <div className='w-full p-4 h-22 bg-blue-100 border rounded-lg w-full'>{tweetDraft.content}</div>
              </div>

              {!!tweetDraft.notes && tweetDraft.notes !== tweetDraft.originalTweet.content && (
                <>
                  <h2>Your Similar Notes</h2>
                  {tweetDraft.notes}
                </>
              )}
              <div className='flex flex-col gap-2 justify-center items-center w-full'>
                <h2>Ideas</h2>
                {tweetDraft.originalTweet.ideas.map((idea) => (
                  <div key={idea.id} className='flex flex-row gap-2 justify-center items-center w-full'>
                    <div className='flex flex-row gap-2 justify-center items-center w-full'>
                      <div className='w-full p-4 h-22 bg-neutral-100 border rounded-lg w-full'>{idea.content}</div>
                    </div>
                  </div>
                ))}
              </div>
            </div>
          </>
        ))}
      </div>
    </>
  );
};
export default MainPage;

Next, we need to create a query that allows us to fetch all of our added notes and ideas that have been embedded in our vector store.

For that, we need to define a new query in our main.wasp file:

query getEmbeddedNotes {
  fn: import { getEmbeddedNotes } from "@server/ideas.js",
  entities: [GeneratedIdea]
}

We then need to create that query at the bottom of our src/actions/ideas.ts file:

// first import the type at the top of the file
import type { GetEmbeddedNotes, GetTweetDraftsWithIdeas } from '@wasp/queries/types';

//...

export const getEmbeddedNotes: GetEmbeddedNotes<never, GeneratedIdea[]> = async (_args, context) => {
  if (!context.user) {
    throw new HttpError(401, 'User is not authorized');
  }

  const notes = await context.entities.GeneratedIdea.findMany({
    where: {
      userId: context.user.id,
      isEmbedded: true,
    },
        orderBy: {
      createdAt: 'desc',
    },
  });

  return notes;
}

Now let’s go back to our src/client/NotesPage.tsx and add our query. Our new file will look like this:

import { useQuery } from '@wasp/queries';
import getEmbeddedNotes from '@wasp/queries/getEmbeddedNotes';

const NotesPage = () => {
  const { data: notes, isLoading, error } = useQuery(getEmbeddedNotes);

  if (isLoading) <div>Loading...</div>;
  if (error) <div>Error: {error.message}</div>;

  return (
    <>
      <h2 className='text-2xl font-bold'>My Notes</h2>
      {notes && notes.length > 0 ? (
        notes.map((note) => (
          <div key={note.id} className='flex flex-col gap-2 justify-center items-center w-full'>
            <div className='flex flex-row gap-2 justify-center items-center w-full'>
              <div className='w-full p-4 h-22 bg-blue-100 border rounded-lg w-full'>{note.content}</div>
            </div>
          </div>
        ))
      ) : notes && notes.length === 0 && (
        <div className='flex flex-col gap-2 justify-center items-center w-full'>
          <div className='w-full p-4 h-22 bg-blue-100 border rounded-lg w-full'>No notes yet</div>
        </div>
      )}
    </>
  );
};

export default NotesPage;

Cool! Now we should be fetching all our embedded notes and ideas, signified by the isEmbedded tag in our postgres database. Your Notes page should now look something like this:

Untitled

You Did it! Your own Twitter Intern 🤖​

Help me help you

🌟 If you haven’t yet, please star us on GitHub, especially if you found this useful! If you do, it helps support us in creating more content like this. And if you don’t… well, we will deal with it, I guess.

https://media.giphy.com/media/3oEjHEmvj6yScz914s/giphy.gif

And that’s it! You’ve now got yourself a semi-autonomous twitter brainstorming agent to help inspire new ideas and keep you actively contributing 🚀

There’s way more you can do with these tools, but this is a great start.

Remember, if you want to see a more advanced version of this app which utilizes the official Twitter API to send tweets, gives you the ability to edit and add generated notes on the fly, has manual similarity search for all your notes, and more, then you can check out the 💥 Banger Tweet Bot 🤖.

And, once again, here's the repo for the finished app we built in this tutorial: Personal Twitter Intern

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

· 46 min read
Vinny

TL;DR​

LangChain, ChatGPT, and other emerging technology have made it possible to build some really creative tools.

In this tutorial, we’ll build a full-stack web app that acts as our own personal Twitter Agent, or “intern”, as I like to call it. It keeps track of your notes and ideas, and uses them — along with tweets from trending-setting twitter users — to brainstorm new ideas and write tweet drafts for you! 💥

BTW, If you get stuck during the tutorial, or at any point just want to check out the full, final repo of the app we're building, here it is: https://github.com/vincanger/twitter-intern

Before We Begin​

Wasp = } is the only open-source, completely serverful fullstack React/Node framework with a built in compiler that lets you build your app in a day and deploy with a single CLI command.

We’re working hard to help you build performant web apps as easily as possibly — including making these tutorials, which are released weekly!

We would be super grateful if you could help us out by starring our repo on GitHub: https://www.github.com/wasp-lang/wasp 🙏

https://media2.giphy.com/media/d0Pkp9OMIBdC0/giphy.gif?cid=7941fdc6b39mgj7h8orvi0f4bjebceyx4gj0ih1xb6s05ujc&ep=v1_gifs_search&rid=giphy.gif&ct=g

…even Ron would star Wasp on GitHub 🤩

Background​

Twitter is a great marketing tool. It’s also a great way to explore ideas and refine your own. But it can be time-consuming and difficult to maintain a tweeting habit.

https://media0.giphy.com/media/WSrR5xkvljaFMe7UPo/giphy.gif?cid=7941fdc6g9o3drj567dbwyuo1c66x76eq8awc2r1oop8oypl&ep=v1_gifs_search&rid=giphy.gif&ct=g

That’s why I decided to build my own personal twitter agent with LangChain on the basis of these assumptions:

🧠 LLMs (like ChatGPT) aren’t the best writers, but they ARE great at brainstorming new ideas.

📊 Certain twitter users drive the majority of discourse within certain niches, i.e. trend-setters influence what’s being discussed at the moment.

💡 the Agent needs context in order to generate ideas relevant to YOU and your opinions, so it should have access to your notes, ideas, tweets, etc.

So instead of trying to build a fully autonomous agent that does the tweeting for you, I thought it would be better to build an agent that does the BRAINSTORMING for you, based on your favorite trend-setting twitter users as well as your own ideas.

Imagine it like an intern that does the grunt work, while you do the curating!

https://media.giphy.com/media/26DNdV3b6dqn1jzR6/giphy.gif

In order to accomplish this, we need to take advantage of a few hot AI tools:

  • Embeddings and Vector Databases
  • LLMs (Large Language Models), such as ChatGPT
  • LangChain and sequential “chains” of LLM calls

Embeddings and Vector Databases give us a powerful way to perform similarity searches on our own notes and ideas.

If you’re not familiar with similarity search, the simplest way to describe what similarity search is by comparing it to a normal google search. In a normal search, the phrase “a mouse eats cheese” will return results with a combination of those words only. But a vector-based similarity search, on the other hand, would return those words, as well as results with related words such as “dog”, “cat”, “bone”, and “fish”.

You can see why that’s so powerful, because if we have non-exact but related notes, our similarity search will still return them!

https://media2.giphy.com/media/xUySTD7evBn33BMq3K/giphy.gif?cid=7941fdc6273if8qfk83gbnv8uabc4occ0tnyzk0g0gfh0qg5&ep=v1_gifs_search&rid=giphy.gif&ct=g

For example, if our favorite trend-setting twitter user makes a post about the benefits of typescript, but we only have a note on “our favorite React hooks”, our similarity search would still likely return such a result. And that’s huge!

Once we get those notes, we can pass them to the ChatGPT completion API along with a prompt to generate more ideas. The result from this prompt will then be sent to another prompt with instructions to generate a draft tweet. We save these sweet results to our Postgres relational database.

This “chain” of prompting is essentially where the LangChain package gets its name 🙂

The flow of information through the app

This approach will give us a wealth of new ideas and tweet drafts related to our favorite trend-setting twitter users’ tweets. We can look through these, edit and save our favorite ideas to our “notes” vector store, or maybe send off some tweets.

I’ve personally been using this app for a while now, and not only has it generated some great ideas, but it also helps to inspire new ones (even if some of the ideas it generates are “meh”), which is why I included an “Add Note” feature front and center to the nav bar

twitter-agent-add-note.png

Ok. Enough background. Let’s start building your own personal twitter intern! 🤖

BTW, if you get stuck at all while following the tutorial, you can always reference this tutorial’s repo, which has the finished app: Twitter Intern GitHub Repo

Configuration​

Set up your Wasp project​

We’re going to make this a full-stack React/NodeJS web app so we need to get that set up first. But don’t worry, it won’t take long AT ALL, because we will be using Wasp as the framework.

Wasp does all the heavy lifting for us. You’ll see what I mean in a second.

# First, install Wasp by running this in your terminal:

curl -sSL https://get.wasp-lang.dev/installer.sh | sh

# next, create a new project:

wasp new twitter-agent

# cd into the new directory and start the project:

cd twitter-agent && wasp start

Great! When running wasp start, Wasp will install all the necessary npm packages, start our server on port 3001, and our React client on port 3000. Head to localhost:3000 in your browser to check it out.

Untitled

Tip ℹ️

you can install the Wasp vscode extension for the best developer experience.

You’ll notice Wasp sets up your full-stack app with a file structure like so:

.
├── main.wasp             # The wasp config file.
└── src
    ├── client            # Your React client code (JS/CSS/HTML) goes here.
    ├── server            # Your server code (Node JS) goes here.
    └── shared            # Your shared (runtime independent) code goes here.

Let’s start adding some server-side code.

Server-Side & Database Entities​

Start by adding a .env.server file in the root directory of your project:

# https://platform.openai.com/account/api-keys
OPENAI_API_KEY=

# sign up for a free tier account at https://www.pinecone.io/
PINECONE_API_KEY=
# will be a location, e.g 'us-west4-gcp-free'
PINECONE_ENV=   

# We will fill these in later during the Twitter Scraping section
# Twitter details -- only needed once for Rettiwt.account.login() to get the tokens 
TWITTER_EMAIL=
TWITTER_HANDLE=
TWITTER_PASSWORD=

# TOKENS -- fill these in after running the getTwitterTokens script in the Twitter Scraping section
KDT=
TWID=
CT0=
AUTH_TOKEN=

We need a way for us to store all our great ideas. So let’s first head to Pinecone.io and set up a free trial account.

Untitled

In the Pinecone dashboard, go to API keys and create a new one. Copy and paste your Environment and API Key into .env.server

Do the same for OpenAI, by creating an account and key at https://platform.openai.com/account/api-keys

Now let’s replace the contents of the main.wasp config file, which is like the “skeleton” of your app, with the code below. This will configure most of the fullstack app for you 🤯

app twitterAgent {
  wasp: {
    version: "^0.10.6"
  },
  title: "twitter-agent",
    head: [
    "<script async src='https://platform.twitter.com/widgets.js' charset='utf-8'></script>"
  ],
  db: { 
    system: PostgreSQL,
  },
  auth: {
    userEntity: User,
    onAuthFailedRedirectTo: "/login",
    methods: {
      usernameAndPassword: {},
    }
  },
  dependencies: [
    ("openai", "3.2.1"),
    ("rettiwt-api", "1.1.8"),
    ("langchain", "0.0.91"),
    ("@pinecone-database/pinecone", "0.1.6"),
    ("@headlessui/react", "1.7.15"),
    ("react-icons", "4.8.0"),
        ("react-twitter-embed", "4.0.4")
  ],
}

// ### Database Models

entity Tweet {=psl
    id              Int           @id @default(autoincrement())
  tweetId         String        
  authorUsername  String
  content         String
  tweetedAt       DateTime      @default(now())
  user            User          @relation(fields: [userId], references: [id])
  userId          Int
  drafts          TweetDraft[]
  ideas           GeneratedIdea[]
psl=}

entity TweetDraft {=psl
  id              Int         @id @default(autoincrement())
  content         String
  notes           String
  originalTweet   Tweet       @relation(fields: [originalTweetId], references: [id])
  originalTweetId Int
  createdAt       DateTime    @default(now())
  user            User        @relation(fields: [userId], references: [id])
  userId          Int
psl=}

entity GeneratedIdea {=psl
  id              Int         @id @default(autoincrement())
  content         String
  createdAt       DateTime    @default(now())
  updatedAt       DateTime    @default(now())
  user            User        @relation(fields: [userId], references: [id])
  userId          Int
  originalTweet   Tweet?      @relation(fields: [originalTweetId], references: [id])
  originalTweetId Int?
  isEmbedded      Boolean     @default(false)
psl=}

entity User {=psl
  id              Int         @id @default(autoincrement())
  username        String      @unique
  password        String
  createdAt       DateTime    @default(now())
  favUsers        String[]
  originalTweets  Tweet[]
  tweetDrafts     TweetDraft[]
  generatedIdeas  GeneratedIdea[]
psl=}

// <<< Client Pages & Routes

route RootRoute { path: "/", to: MainPage }
page MainPage {
  authRequired: true,
  component: import Main from "@client/MainPage"
}

//...
note

You might have noticed this {=psl psl=} syntax in the entities above. This denotes that anything in between these psl brackets is actually a different language, in this case, Prisma Schema Language. Wasp uses Prisma under the hood, so if you've used Prisma before, it should be straightforward.

As you can see, our main.wasp config file has our:

  • dependencies,
  • authentication method,
  • database type, and
  • database models (”entities”)

With this, our app structure is mostly defined and Wasp will take care of a ton of configuration for us.

Database Setup​

But we still need to get a postgres database running. Usually this can be pretty annoying, but with Wasp, just have Docker Deskop installed and running, then open up another separate terminal tab/window and then run:

wasp start db

This will start and connect your app to a Postgres database for you. No need to do anything else! 🤯 Just leave this terminal tab, along with docker desktop, open and running in the background.

In a different terminal tab, run: 

wasp db migrate-dev

and make sure to give your database migration a name.

If you stopped the wasp dev server to run this command, go ahead and start it again with wasp start.

At this point, our app will be navigating us to localhost:3000/login but because we haven’t implemented a login screen/flow yet, we will be seeing a blank screen. Don’t worry, we’ll get to that.

Embedding Ideas & Notes​

Server Action​

First though, in the main.wasp config file, let’s define a server action for saving notes and ideas. Go ahead and add the code below to the bottom of the file:

// main.wasp

//...
// <<< Client Pages & Routes

route RootRoute { path: "/", to: MainPage }
page MainPage {
  authRequired: true,
  component: import Main from "@client/MainPage"
}

// !!! Actions

action embedIdea {
  fn: import { embedIdea } from "@server/ideas.js",
  entities: [GeneratedIdea]
}

With the action declared, let’s create it. Make a new file, .src/server/ideas.ts in and add the following code:

import type { EmbedIdea } from '@wasp/actions/types';
import type { GeneratedIdea } from '@wasp/entities';
import HttpError from '@wasp/core/HttpError.js';
import { PineconeStore } from 'langchain/vectorstores/pinecone';
import { Document } from 'langchain/document';
import { OpenAIEmbeddings } from 'langchain/embeddings/openai';
import { PineconeClient } from '@pinecone-database/pinecone';

const pinecone = new PineconeClient();
export const initPinecone = async () => {
  await pinecone.init({
    environment: process.env.PINECONE_ENV!,
    apiKey: process.env.PINECONE_API_KEY!,
  });
  return pinecone;
};

export const embeddings = new OpenAIEmbeddings({
  openAIApiKey: process.env.OPENAI_API_KEY,
});

/**
 * Embeds a single idea into the vector store
 */
export const embedIdea: EmbedIdea<{ idea: string }, GeneratedIdea> = async ({ idea }, context) => {
  if (!context.user) {
    throw new HttpError(401, 'User is not authorized');
  }

  console.log('idea: ', idea);

  try {
    let newIdea = await context.entities.GeneratedIdea.create({
        data: {
          content: idea,
          userId: context.user.id,
        },
      });
    

    if (!newIdea) {
      throw new HttpError(404, 'Idea not found');
    }

    const pinecone = await initPinecone();
        
    // we need to create an index to save the vector embeddings to
    // an index is similar to a table in relational database world
    const availableIndexes = await pinecone.listIndexes();
    if (!availableIndexes.includes('embeds-test')) {
      console.log('creating index');
      await pinecone.createIndex({
        createRequest: {
          name: 'embeds-test',
          // open ai uses 1536 dimensions for their embeddings
          dimension: 1536, 
        },
      });
    }

    const pineconeIndex = pinecone.Index('embeds-test');
        
    // the LangChain vectorStore wrapper
    const vectorStore = new PineconeStore(embeddings, {
      pineconeIndex: pineconeIndex,
      namespace: context.user.username,
    });
        
    // create a document with the idea's content to be embedded
    const ideaDoc = new Document({
      metadata: { type: 'note' },
      pageContent: newIdea.content,
    });
        
    // add the document to the vectore store along with its id
    await vectorStore.addDocuments([ideaDoc], [newIdea.id.toString()]);

    newIdea = await context.entities.GeneratedIdea.update({
      where: {
        id: newIdea.id,
      },
      data: {
        isEmbedded: true,
      },
    });
    console.log('idea embedded successfully!', newIdea);
    return newIdea;
  } catch (error: any) {
    throw new Error(error);
  }
};
info

We’ve defined the action function in our main.wasp file as coming from ‘@server/ideas.js’ but we’re creating an ideas.ts file. What's up with that?!

Well, Wasp internally uses esnext module resolution, which always requires specifying the extension as .js (i.e., the extension used in the emitted JS file). This applies to all @server imports (and files on the server in general). It does not apply to client files.

Great! Now we have a server action for adding notes and ideas to our vector database. And we didn’t even have to configure a server ourselves (thanks, Wasp 🙂).

Let's take a step back and walk through the code we just wrote though:

  1. We create a new Pinecone client and initialize it with our API key and environment.
  2. We create a new OpenAIEmbeddings client and initialize it with our OpenAI API key.
  3. We create a new index in our Pinecone database to store our vector embeddings.
  4. We create a new PineconeStore, which is a LangChain wrapper around our Pinecone client and our OpenAIEmbeddings client.
  5. We create a new Document with the idea’s content to be embedded.
  6. We add the document to the vector store along with its id.
  7. We also update the idea in our Postgres database to mark it as embedded.

Now we want to create the client-side functionality for adding ideas, but you’ll remember we defined an auth object in our wasp config file. So we’ll need to add the ability to log in before we do anything on the frontend.

Authentication​

Let’s add that quickly by adding a new a Route and Page definition to our main.wasp file

//...

route LoginPageRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import Login from "@client/LoginPage"
}

…and create the file src/client/LoginPage.tsx with the following content:

import { LoginForm } from '@wasp/auth/forms/Login';
import { SignupForm } from '@wasp/auth/forms/Signup';
import { useState } from 'react';

export default () => {
  const [showSignupForm, setShowSignupForm] = useState(false);

  const handleShowSignupForm = () => {
    setShowSignupForm((x) => !x);
  };

  return (
    <>
      {showSignupForm ? <SignupForm /> : <LoginForm />}
      <div onClick={handleShowSignupForm} className='underline cursor-pointer hover:opacity-80'>
        {showSignupForm ? 'Already Registered? Login!' : 'No Account? Sign up!'}
      </div>
    </>
  );
};
info

In the auth object on the main.wasp file, we used the usernameAndPassword method which is the simplest form of auth Wasp offers. If you’re interested, Wasp does provide abstractions for Google, Github, and Email Verified Authentication, but we will stick with the simplest auth for this tutorial.

With authentication all set up, if we try to go to localhost:3000 we will be automatically directed to the login/register form.

You’ll see that Wasp creates Login and Signup forms for us because of the auth object we defined in the main.wasp file. Sweet! 🎉

But even though we’ve added some style classes, we haven’t set up any css styling so it will probably be pretty ugly right about now.

🤢 Barf.

Untitled

Adding Tailwind CSS​

Luckily, Wasp comes with tailwind css support, so all we have to do to get that working is add the following files in the root directory of the project:

.
├── main.wasp            
├── src
│   ├── client            
│   ├── server           
│   └── shared            
├── postcss.config.cjs       # add this file here
├── tailwind.config.cjs      # and this here too
└── .wasproot

postcss.config.cjs

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

tailwind.config.cjs

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

Finally, replace the contents of your src/client/Main.css file with these lines:

@tailwind base;
@tailwind components;
@tailwind utilities;

Now we’ve got the magic of tailwind css on our sides! 🎨 We’ll get to styling later though. Patience, young grasshopper.

Adding Notes Client-side​

From here, let’s create the complimentary client-side components for adding notes to the vector store. Create a new .src/client/AddNote.tsx file with the following contents:

import { useState } from 'react';
import embedIdea from '@wasp/actions/embedIdea';

export default function AddNote() {
  const [idea, setIdea] = useState('');
  const [isIdeaEmbedding, setIsIdeaEmbedding] = useState(false);

  const handleEmbedIdea = async (e: any) => {
    try {
      setIsIdeaEmbedding(true);
      if (!idea) {
        throw new Error('Idea cannot be empty');
      }
      const embedIdeaResponse = await embedIdea({
        idea,
      });

      console.log('embedIdeaResponse: ', embedIdeaResponse);
    } catch (error: any) {
      alert(error.message);
    } finally {
      setIdea('');
      setIsIdeaEmbedding(false);
    }
  };

  return (
    <div className='flex flex-row gap-2 justify-center items-end w-full'>
      <textarea
        autoFocus
        onChange={(e) => setIdea(e.target.value)}
        value={idea}
        placeholder='LLMs are great for brainstorming!'
        className='w-full p-4 h-22 bg-neutral-100 border rounded-lg w-full'
      />
      <button
        onClick={handleEmbedIdea}
        className='flex flex-row justify-center items-center bg-neutral-100 hover:bg-neutral-200 border border-neutral-300 font-bold px-3 py-1 text-sm text-blue-500 whitespace-nowrap rounded-lg'
      >
        {isIdeaEmbedding ? 'Loading...' : 'Save Note'}
      </button>
    </div>
  );
}

Here we’re using the embedIdea action we defined earlier to add our idea to the vector store. We’re also using the useState hook to keep track of the idea we’re adding, as well as the loading state of the button.

So now we have a way to add our own ideas and notes to our vector store. Pretty sweet!

Generating New Ideas & Tweet Drafts​

Using LangChain's Sequential Chains​

Now we need to set up the sequential chain of LLM calls that LangChain is so great at.

Here are the steps we will take:

  1. define a function that uses LangChain to initiate a “chain” of API calls to OpenAI’s ChatGPT completions endpoint.
    1. this function takes a tweet that we pulled from one of our favorite twitter users as an argument, searches our vector store for similar notes & ideas, and returns a list of new “brainstormed” based on the example tweet and our notes.
  2. define a new action that loops through our favorite users array, pulls their most recent tweets, and sends them to our LangChain function mentioned above

So let’s start again by creating our LangChain function. Make a new src/server/chain.ts file:

import { ChatOpenAI } from 'langchain/chat_models/openai';
import { LLMChain, SequentialChain } from 'langchain/chains';
import { PromptTemplate } from 'langchain/prompts';
import { PineconeStore } from 'langchain/vectorstores/pinecone';
import { OpenAIEmbeddings } from 'langchain/embeddings/openai';
import { PineconeClient } from '@pinecone-database/pinecone';

const pinecone = new PineconeClient();
export const initPinecone = async () => {
  await pinecone.init({
    environment: process.env.PINECONE_ENV!,
    apiKey: process.env.PINECONE_API_KEY!,
  });
  return pinecone;
};

const embeddings = new OpenAIEmbeddings({
  openAIApiKey: process.env.OPENAI_API_KEY,
});

export const generateIdeas = async (exampleTweet: string, username: string) => {
  try {
    // remove quotes and curly braces as not to confuse langchain template parser
    exampleTweet = exampleTweet.replace(/"/g, '');
    exampleTweet = exampleTweet.replace(/{/g, '');
    exampleTweet = exampleTweet.replace(/}/g, '');

    const pinecone = await initPinecone();

    console.log('list indexes', await pinecone.listIndexes());

    // find the index we created earlier
    const pineconeIndex = pinecone.Index('embeds-test');

    const vectorStore = new PineconeStore(embeddings, {
      pineconeIndex: pineconeIndex,
      namespace: username,
    });

    //
    // sequential tweet chain begin --- >
    //
    /**
     * vector store results for notes similar to the original tweet
     */
    const searchRes = await vectorStore.similaritySearchWithScore(exampleTweet, 2);
    console.log('searchRes: ', searchRes);
    let notes = searchRes
      .filter((res) => res[1] > 0.7) // filter out strings that have less than %70 similarity
      .map((res) => res[0].pageContent)
      .join(' ');

    console.log('\n\n similarity search results of our notes-> ', notes);

        if (!notes || notes.length <= 2) {
      notes = exampleTweet;
    }

    const tweetLlm = new ChatOpenAI({
      openAIApiKey: process.env.OPENAI_API_KEY,
      temperature: 0.8, // 0 - 2 with 0 being more deterministic and 2 being most "loose". Past 1.3 the results tend to be more incoherent.
      modelName: 'gpt-3.5-turbo',
    });

    const tweetTemplate = `You are an expert idea generator. You will be given a user's notes and your goal is to use this information to brainstorm other novel ideas. 

      Notes: {notes}
    
      Ideas Brainstorm: 
      -`;

    const tweetPromptTemplate = new PromptTemplate({
      template: tweetTemplate,
      inputVariables: ['notes'],
    });

    const tweetChain = new LLMChain({
      llm: tweetLlm,
      prompt: tweetPromptTemplate,
      outputKey: 'newTweetIdeas',
    });

    const interestingTweetTemplate = `You are an expert interesting tweet generator. You will be given some tweet ideas and your goal is to choose one, and write a tweet based on it. Structure the tweet in an informal yet serious tone and do NOT include hashtags in the tweet!
 
      Tweet Ideas: {newTweetIdeas}
      
      Interesting Tweet:`;

    const interestingTweetLlm = new ChatOpenAI({
      openAIApiKey: process.env.OPENAI_API_KEY,
      temperature: 1.1,
      modelName: 'gpt-3.5-turbo',
    });

    const interestingTweetPrompt = new PromptTemplate({
      template: interestingTweetTemplate,
      inputVariables: ['newTweetIdeas'],
    });

    const interestingTweetChain = new LLMChain({
      llm: interestingTweetLlm,
      prompt: interestingTweetPrompt,
      outputKey: 'interestingTweet',
    });

    const overallChain = new SequentialChain({
      chains: [tweetChain, interestingTweetChain],
      inputVariables: ['notes'],
      outputVariables: ['newTweetIdeas', 'interestingTweet'],
      verbose: false,
    });

    type ChainDraftResponse = {
      newTweetIdeas: string;
      interestingTweet: string;
      notes: string;
    };

    const res1 = (await overallChain.call({
      notes,
    })) as ChainDraftResponse;

    return {
      ...res1,
      notes,
    };
  } catch (error: any) {
    throw new Error(error);
  }
};

Great! Let's run through the above code real quick:

  1. Initialize the Pinecone client
  2. Find our pinecone index (i.e. table) that we created earlier and initialize a new PineconeStore with LangChain
  3. Search our vector store for notes similar to the example tweet, filtering out any results that have less than %70 similarity
  4. Create a new ChatGPT completion chain that takes our notes as input and generates new tweet ideas
  5. Create a new ChatGPT completion chain that takes the new tweet ideas as input and generates a new tweet draft
  6. Create a new SequentialChain and combine the above two chains together so that we can pass it our notes as input and it returns the new tweet ideas and the new tweet draft as output
VECTOR COSINE SIMILARITY SCORES

A good similarity threshold for cosine similarity search on text strings depends on the specific application and the desired level of strictness in matching. Cosine similarity scores range between 0 and 1, with 0 meaning no similarity and 1 meaning completely identical text strings.

  • 0.8-0.9 = strict
  • 0.6-0.8 = moderate
  • 0.5 = relaxed.

In our case, we went for a moderate similarity threshold of 0.7, which means that we will only return notes that are at least 70% similar to the example tweet.

With this function, we will get our newTweetIdeas and our interestingTweet draft back as results that we can use within our server-side action.

Scraping Twitter​

Before we can pass an exampleTweet as an argument to our newly created Sequential Chain, we need to fetch it first!

To do this, we're going to use the Rettiwt-Api (which is just Twitter written backwards). Because it's an unofficial API there are a few caveats:

  1. We have to use the rettiwt client to login to our twitter account once. We will output the tokens it returns via a script and save those in our .env.server file for later.
  2. It's best to use an alternative account for this process. If you don't have an alternative account, go ahead and register a new one now.
⚠️

The use of an unofficial Twitter client, Rettiwt, is for illustrative purposes only. It's crucial that you familiarize yourself with Twitter's policies and rules regarding scraping before implementing these methods. Any abuse or misuse of these scripts and techniques may lead to actions taken against your Twitter account. We hold no responsibility for any consequences arising from your personal use of this tutorial and/or the related scripts. It is intended purely for learning and educational purposes.

Let's go ahead and create a new folder in src/server called scripts with a file inside called tokens.ts. This will be our script that we will run only once, just so that we get the necessary tokens to pass to our Rettiwt client.

We want to avoid running this script many times otherwise our account could get rate-limited. This shouldn't be an issue though, because once we return the tokens, they are valid for up to a year.

So inside src/server/scripts/tokens.ts add the following code:

import { Rettiwt } from 'rettiwt-api'; 

/**
 * This is a script we can now run from the cli with `wasp db seed`
 * IMPORTANT! We only want to run this script once, after which we save the tokens
 * in the .env.server file. They should be good for up to a year.
 */
export const getTwitterTokens = async () => {
  const tokens = await Rettiwt().account.login(
    process.env.TWITTER_EMAIL!,
    process.env.TWITTER_HANDLE!,
    process.env.TWITTER_PASSWORD!
  );

  console.log('tokens: ', tokens)
};

Make sure to add your twitter login details to our .env.server file, if you haven't already!

Great. To be able to run this script via a simple Wasp CLI command, add it via the seeds array within the db object at the top of your main.wasp file:

app twitterAgent {
  wasp: {
    version: "^0.10.6"
  },
  //...
  db: { 
    system: PostgreSQL,
    seeds: [ // <---------- add this
      import { getTwitterTokens } from "@server/scripts/tokens.js",
    ]
  },
  //...

Nice! Now for the fun part :)

in your terminal, at the root of your project, run wasp db seed, and you should see the tokens output to the terminal similar to this:

[Db]      Running seed: getTwitterTokens
[Db]      tokens:  { // your tokens... }

Copy and paste those tokens into your .env.server file:


# TOKENS -- fill these in after running the getTwitterTokens script in the Twitter Scraping section
KDT='...'
TWID='...'
CT0='...'
AUTH_TOKEN='...'

Now with that, we should be able to access our favorite trend-setting users' recent tweets and use them to help us brainstorm new ideas!

Server Action​

Ok, so we've got the tokens we need to get our trend-setting example tweets, and we've got a function that runs our similarity search and sequential chain of LLM calls.

Now let’s define an action in our main.wasp file that pulls it all together:

// actions...

action generateNewIdeas {
  fn: import { generateNewIdeas } from "@server/ideas.js",
  entities: [GeneratedIdea, Tweet, TweetDraft, User]
}

…and then create that action within src/server/ideas.ts


import type { 
    EmbedIdea,
    GenerateNewIdeas // < ---- add this type here -----
 } from '@wasp/actions/types';
// ... other imports ...
import { generateIdeas } from './chain.js'; // < ---- this too -----
import { Rettiwt } from 'rettiwt-api'; // < ---- and this here -----

const twitter = Rettiwt({ // < ---- and this -----
  kdt: process.env.KDT!,
  twid: process.env.TWID!,
  ct0:  process.env.CT0!,
  auth_token: process.env.AUTH_TOKEN!,
}); 

//... other stuff ...

export const generateNewIdeas: GenerateNewIdeas<unknown, void> = async (_args, context) => {
    try {
    // get the logged in user that Wasp passes to the action via the context
    const user = context.user

    if (!user) {
      throw new HttpError(401, 'User is not authorized');
    }

      for (let h = 0; h < user.favUsers.length; h++) {
        const favUser = user.favUsers[h];
        const oneDayFromNow = new Date(Date.now() + 24 * 60 * 60 * 1000);
        // convert oneDayFromNow to format YYYY-MM-DD
        const endDate = oneDayFromNow.toISOString().split('T')[0];

        // find the most recent tweet from the favUser
        const mostRecentTweet = await context.entities.Tweet.findFirst({
          where: {
            authorUsername: favUser,
          },
          orderBy: {
            tweetedAt: 'desc',
          },
        });

        console.log('mostRecentTweet: ', mostRecentTweet)

        const favUserTweets = await twitter.tweets.getTweets({
          fromUsers: [favUser],
          sinceId: mostRecentTweet?.tweetId || undefined, // get tweets since the most recent tweet if it exists
          endDate: endDate, // endDate in format YYYY-MM-DD
        });

        const favUserTweetTexts = favUserTweets.list

        for (let i = 0; i < favUserTweetTexts.length; i++) {
          const tweet = favUserTweetTexts[i];

          const existingTweet = await context.entities.User.findFirst({
            where: {
              id: user.id,
            },
            select: {
              originalTweets: {
                where: {
                  tweetId: tweet.id,
                },
              },
            },
          });

          /** 
           * If the tweet already exists in the database, skip generating drafts and ideas for it.
           */
          if (existingTweet) {
            console.log('tweet already exists in db, skipping generating drafts...');
            continue;
          }
          
          /**
           * this is where the magic happens
           */
          const draft = await generateIdeas(tweet.fullText, user.username);
          console.log('draft: ', draft);

          const originalTweet = await context.entities.Tweet.create({
            data: {
              tweetId: tweet.id,
              content: tweet.fullText,
              authorUsername: favUser,
              tweetedAt: new Date(tweet.createdAt),
              userId: user.id
            },
          });

          let newTweetIdeas = draft.newTweetIdeas.split('\n');
          newTweetIdeas = newTweetIdeas
            .filter((idea) => idea.trim().length > 0)
            .map((idea) => {
              // remove all dashes that are not directly followed by a letter
              idea = idea.replace(/-(?![a-zA-Z])/g, '');
              idea = idea.replace(/"/g, '');
              idea = idea.replace(/{/g, '');
              idea = idea.replace(/}/g, '');
              // remove hashtags and the words that follow them
              idea = idea.replace(/#[a-zA-Z0-9]+/g, '');
              idea = idea.replace(/^\s*[\r\n]/gm, ''); // remove new line breaks
              idea = idea.trim();
              // check if last character contains punctuation and if not add a period
              if (idea.length > 1 && !idea[idea.length - 1].match(/[.,\/#!$%\^&\*;:{}=\-_`~()]/g)) {
                idea += '.';
              }
              return idea;
            });
          for (let j = 0; j < newTweetIdeas.length; j++) {
            const newTweetIdea = newTweetIdeas[j];
            const newIdea = await context.entities.GeneratedIdea.create({
              data: {
                content: newTweetIdea,
                originalTweetId: originalTweet.id,
                userId: user.id
              },
            });
            console.log('newIdea saved to DB: ', newIdea);
          }

          const interestingTweetDraft = await context.entities.TweetDraft.create({
            data: {
              content: draft.interestingTweet,
              originalTweetId: originalTweet.id,
              notes: draft.notes,
              userId: user.id
            },
          });

          console.log('interestingTweetDraft saved to DB: ', interestingTweetDraft);

          // create a delay to avoid rate limiting
          await new Promise((resolve) => setTimeout(resolve, 1000));

        }
        await new Promise((resolve) => setTimeout(resolve, 1000));
      }

  } catch (error: any) {
    console.log('error', error);
    throw new HttpError(500, error);
  }
}

Ok! Nice work. There’s a lot going on above, so let’s just recap:

  • We loop through the array of our favorite users, as defined on our user entity in main.wasp,
  • Pull that user’s most recent tweets
  • Send that tweet to our generateIdeas function, which
    • searches our vector store for similar notes
    • asks GPT to generate similar, new ideas
    • sends those ideas in another prompt GPT to create a new, interesting tweet
    • returns the new ideas and interesting tweet
  • Create new GeneratedIdeas and a TweetDraft and saves them to our Postgres DB

Phew! We’re doing it 💪 

Fetching & Displaying Ideas​

Defining a Server-side Query​

Since we now have our chain of GPT prompts defined via LangChain and our server-side action, let’s go ahead and start implementing some front-end logic to fetch that data and display it to our users… which is basically only us at this point 🫂.

Just as we added a server-side action to generateNewIdeas we will now define a query to fetch those ideas.

Add the following query to your main.wasp file:

query getTweetDraftsWithIdeas {
  fn: import { getTweetDraftsWithIdeas } from "@server/ideas.js",
  entities: [TweetDraft]
}

In your src/server/ideas.ts file, below your generateNewIdeas action, add the query we just defined in our wasp file:

//... other imports ...
import type { GetTweetDraftsWithIdeas } from '@wasp/queries/types'; // <--- add this ---

// ... other functions ...

type TweetDraftsWithIdeas = {
  id: number;
  content: string;
  notes: string;
  createdAt: Date;
  originalTweet: {
    id: number;
    content: string;
    tweetId: string;
    tweetedAt: Date;
    ideas: GeneratedIdea[];
    authorUsername: string;
  };
}[];

export const getTweetDraftsWithIdeas: GetTweetDraftsWithIdeas<unknown, TweetDraftsWithIdeas> = async (_args, context) => {
  if (!context.user) {
    throw new HttpError(401, 'User is not authorized');
  }

  const drafts = await context.entities.TweetDraft.findMany({
    orderBy: {
      originalTweet: {
        tweetedAt: 'desc',
      }
    },
    where: {
      userId: context.user.id,
      createdAt: {
        gte: new Date(Date.now() - 2 * 24 * 60 * 60 * 1000), // Get drafts created within the last 2 days
      },
    },
    select: {
      id: true,
      content: true,
      notes: true,
      createdAt: true,
      originalTweet: {
        select: {
          id: true,
          tweetId: true,
          content: true,
          ideas: true,
          tweetedAt: true,
                    authorUsername: true,
        },
      },
    },
  });

  return drafts;
};

With this function we will be returning the tweet drafts we generate, along with our notes, the original tweet that inspired it, and the newly generated ideas.

Sweet!

Ok, but what good is a function that fetches the data if we’ve got nowhere to display it!?

Displaying Ideas Client-side​

Let’s go now to our src/client/MainPage.tsx file (make sure it’s got the .tsx extension and not .jsx) and replace the contents with these below:

import waspLogo from './waspLogo.png'
import './Main.css'

const MainPage = () => {
  return (
    <div className='min-h-screen bg-neutral-300/70 text-center'>
      <div className='flex flex-col justify-center items-center mx-auto pt-12'>
        <img src={waspLogo} className='w-5' />
      </div>
    </div>
  )
}
export default MainPage

At this point, you. might need to restart the wasp dev server running in your terminal to get the tailwind configuration to take effect (ctrl + c, then wasp start again).

You’ll now be prompted with the login / register screen. Go ahead and click on register and you will be automatically logged in and redirected to the main page, which at this point only has this:

Untitled

Let’s go back to our MainPage.tsx file and add the magic!

https://media3.giphy.com/media/ekv45izCuyXkXoHRaL/giphy.gif?cid=7941fdc6c3dszwj4xaoxg2kyj6xxdubjxn69m4qruhomhkut&ep=v1_gifs_search&rid=giphy.gif&ct=g

First, let’s create a buttons component so we don’t have to constantly style a new button. Create a new src/client/Button.tsx file:

import { ButtonHTMLAttributes } from 'react';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  isLoading?: boolean;
}

export default function Button({ isLoading, children, ...otherProps }: ButtonProps) {
  return (
    <button
      {...otherProps}
      className={`flex flex-row justify-center items-center bg-neutral-100 hover:bg-neutral-200 border border-neutral-300 text-blue-500 font-bold px-3 py-1 text-sm rounded-lg ${isLoading ? ' pointer-events-none opacity-70' : 'cursor-pointer'}`}
    >
      {isLoading? 'Loading...' : children}
    </button>
  );
}

Now let’s add it to your AddNote.tsx component, replacing the original button with this one. The whole file should look like this:

import { useState } from 'react';
import embedIdea from '@wasp/actions/embedIdea';
import Button from './Button';

export default function AddNote() {
  const [idea, setIdea] = useState('');
  const [isIdeaEmbedding, setIsIdeaEmbedding] = useState(false);

  const handleEmbedIdea = async (e: any) => {
    try {
      setIsIdeaEmbedding(true);
      if (!idea) {
        throw new Error('Idea cannot be empty');
      }
      const embedIdeaResponse = await embedIdea({
        idea,
      });

      console.log('embedIdeaResponse: ', embedIdeaResponse);
    } catch (error: any) {
      alert(error.message);
    } finally {
      setIdea('');
      setIsIdeaEmbedding(false);
    }
  };

  return (
    <div className='flex flex-row gap-2 justify-center items-end w-full'>
      <textarea
        autoFocus
        onChange={(e) => setIdea(e.target.value)}
        value={idea}
        placeholder='LLMs are great for brainstorming!'
        className='w-full p-4 h-22 bg-neutral-100 border rounded-lg w-full'
      />
      <Button isLoading={isIdeaEmbedding} onClick={handleEmbedIdea}>
        Save Note
      </Button>
    </div>
  );
}

Noice.

Next, we want our page to perform the following actions:

  1. create a button that runs our generateNewIdeas action when clicked
  2. define the query that fetches and caches the tweet drafts and ideas
  3. loop through the results and display them on the page

That’s exactly what the below code will do. Go ahead and replace the MainPage with it and take a minute to review what’s going on:

import waspLogo from './waspLogo.png';
import './Main.css';
import { useState } from 'react';
import generateNewIdeas from '@wasp/actions/generateNewIdeas';
import { useQuery } from '@wasp/queries';
import getTweetDraftsWithIdeas from '@wasp/queries/getTweetDraftsWithIdeas';
import AddNote from './AddNote';
import Button from './Button';

const MainPage = () => {
  const [isGenerating, setIsGenerating] = useState(false);

  const {
    data: tweetDrafts,
    isLoading: isTweetDraftsLoading,
    error: tweetDraftsError,
  } = useQuery(getTweetDraftsWithIdeas);

  const handleNewIdeas = async (e: any) => {
    try {
      setIsGenerating(true);
      await generateNewIdeas();
    } catch (error: any) {
      alert(error.message);
    } finally {
      setIsGenerating(false);
    }
  };

  if (isTweetDraftsLoading) {
    return 'Loading...';
  }

  if (tweetDraftsError) {
    return 'Error: ' + tweetDraftsError.message;
  }

  return (
    <div className='min-h-screen bg-neutral-300/70 text-center'>
      <div className='flex flex-col gap-6 justify-center items-center mx-auto pt-12'>
        <img src={waspLogo} className='w-5' />
        <div className='flex flex-col gap-4 justify-center items-center w-2/4'>
          <AddNote />
          <hr className='border border-t-1 border-neutral-100/70 w-full' />
          <div className='flex flex-row justify-center w-1/4'>
            <Button onClick={handleNewIdeas} isLoading={isGenerating}>
              Generate New Ideas
            </Button>
          </div>
          <div className='flex flex-col gap-4 justify-center items-center w-full'>
            {tweetDrafts.map((tweetDraft) => (
              <>
                <h2 className='text-2xl font-bold'>Generated Ideas</h2>
                <div key={tweetDraft.id} className='flex flex-col gap-2 justify-center items-center w-full'>
                  <h2>Tweet Draft</h2>
                  <div className='flex flex-row gap-2 justify-center items-center w-full'>
                    <div className='w-full p-4 h-22 bg-blue-100 border rounded-lg w-full'>{tweetDraft.content}</div>
                  </div>

                  {!!tweetDraft.notes && tweetDraft.notes !== tweetDraft.originalTweet.content && (
                    <>
                      <h2>Your Similar Notes</h2>
                      {tweetDraft.notes}
                    </>
                  )}
                  <div className='flex flex-col gap-2 justify-center items-center w-full'>
                    <h2>Ideas</h2>
                    {tweetDraft.originalTweet.ideas.map((idea) => (
                      <div key={idea.id} className='flex flex-row gap-2 justify-center items-center w-full'>
                        <div className='flex flex-row gap-2 justify-center items-center w-full'>
                          <div className='w-full p-4 h-22 bg-neutral-100 border rounded-lg w-full'>{idea.content}</div>
                        </div>
                      </div>
                    ))}
                  </div>
                </div>
              </>
            ))}
          </div>
        </div>
      </div>
    </div>
  );
};
export default MainPage;

This is what you should see on the homepage now! 🎉

Untitled

But, if you clicked ‘generate new ideas’ and nothing happened, well that’s because we haven’t defined any favorite trend-setting twitter users to scrape tweets from. And there’s no way to do that from the UI at the moment, so let’s open up the database manager and add some manually.

In a new terminal tab, in the root of your project, run:

wasp db studio

Then, in a new browswer tab, at localhost:5555 you should see your database.

Go to user, and you should be the only user in there. Add the usernames of a couple of your favorite trend-setting twitter users.

Untitled

Make sure the accounts have tweeted recently or your function won’t be able to scrape or generate anything!

Hey ✋

While you’re at it, if you’re liking this tutorial, give me a follow @hot_town for more future content like this

After adding the twitter usernames, make sure you click save 1 change.

Go back to your client and click the Generate New Ideas button again. This might take a while depending on how many tweets it’s generating ideas for, so be patient — and watch the console output in your terminal if you’re curious ;)

Untitled

Awesome! Now we should be getting back some generated ideas from our twitter “intern” which will help us brainstorm further notes and generate our own BANGER TWEETS.

But it would be cool to also display the tweet these ideas are referencing from the beginning. That way we’d have a bit more context on where the ideas came from.

Let’s do that then! In your MainPage file, at the very top, add the following import:

import { TwitterTweetEmbed } from 'react-twitter-embed';

This allows us to embed tweets with that nice twitter styling.

We already added this dependency to our main.wasp file at the beginning of the tutorial, so we can just import and start embedding tweets.

Let’s try it out now in our MainPage by adding the following snippet above our <h2>Tweet Draft</h2> element:

//...

<h2>Original Tweet</h2>
<div className='flex flex-row gap-2 justify-center items-center w-full'>
  <TwitterTweetEmbed tweetId={tweetDraft.originalTweet.tweetId} />
</div>

<h2>Tweet Draft</h2>
//...

Great. Now we should be sitting pretty 😻

Untitled

You might remember from the beginning of the tutorial when we defined the LLM calls, that if your vector store notes don’t turn back a cosine similarity of at least 0.7, your agent will generate its own ideas entirely without using your notes as a guide.

And since we have NO notes in our vector store at the moment, that’s exactly what it is doing. Which is fine, because we can let it brainstorm for us, and we can select our favorite notes and edit and add them as we see fit.

So you can go ahead and start adding notes whenever you feel like it 📝.

But, we’ve added our favorite twitter users to the database manually. It would be preferable to do it via an account settings page, right? Let’s make one then.

Creating an Account Settings Page​

First, add the route and page to your main.wasp config file, under the other routes:

//...

route AccountRoute { path: "/account", to: AccountPage }
page AccountPage {
  authRequired: true,
  component: import Account from "@client/AccountPage"
}

Next, let’s create a new page, src/client/AccountPage.tsx:

import Button from './Button';
import { ChangeEvent, useEffect, useState } from 'react';
import logout from '@wasp/auth/logout';
import type { User } from '@wasp/entities';

const AccountPage = ({ user }: { user: User }) => {
  return (
        <div className='flex flex-col justify-center items-center mt-12 w-full'>
      <div className='flex flex-col items-center justify-center gap-4 border border-neutral-700 bg-neutral-100/40 rounded-xl p-1 sm:p-4 w-full'>
        <div className='flex flex-row justify-end w-full px-4 pt-2'>
          <Button onClick={logout}>Logout</Button>
        </div>
        {JSON.stringify(user, null, 2)}
      </div>
    </div>
  );
};

export default AccountPage;

When you navigate to localhost:3000/account, you’ll notice two things, one of them being a logout button. You can see in our SettingsPage above that we imported a Wasp-provided logout function. We get this “for free” since we defined our auth strategy in the main.wasp file — a big time-saver!

Untitled

Because we also defined the AccountPage route with the authRequired: true property, Wasp will automatically pass the logged in user as a prop argument to our page. We can use the user object to display and update our favUsers, just as we can see in the image above.

To do that, let’s define a new updateAccount action in our main.wasp file:

action updateAccount {
  fn: import { updateAccount } from "@server/account.js",
  entities: [User]
}

Next, let’s create the updateAccount action in a new file, src/server/account.ts:

import type { UpdateAccount } from "@wasp/actions/types";
import HttpError from "@wasp/core/HttpError.js";

export const updateAccount: UpdateAccount<{ favUsers: string[] }, void> = async ({ favUsers }, context) => {
  if (!context.user) {
    throw new HttpError(401, "User is not authorized");
  }

  try {
    await context.entities.User.update({
      where: { id: context.user.id },
      data: { favUsers },
    });
    
  } catch (error: any) {
    throw new HttpError(500, error.message);
  }
}

Right. Now it’s time to put it all together in our Account page. We’re going to create a form for adding new twitter users to scrape tweets from, so at the bottom of your src/client/AccountPage.tsx, below your other code, add the following component:

function InputFields({ user }: { user: User }) {
  const [isLoading, setIsLoading] = useState(false);
  const [fields, setFields] = useState(['']);

  useEffect(() => {
    if (user?.favUsers.length > 0) {
      setFields(user.favUsers);
    }
  }, [user?.favUsers]);

  const handleAdd = () => {
    setFields([...fields, '']);
  };

  const handleRemove = () => {
    const newFields = [...fields];
    newFields.splice(fields.length - 1, 1);
    setFields(newFields);
  };

  const handleChange = (e: ChangeEvent<HTMLInputElement>, index: number) => {
    const newFields = [...fields];
    newFields[index] = e.target.value;
    setFields(newFields);
  };

  const handleSubmit = async () => {
    //...
  };

  return (
    <div className='w-full p-4'>
      <div className='flex flex-row justify-start items-start'>
        <h2 className='ml-1 font-bold'>Trend-Setting Twitter Accounts</h2>
      </div>
      {fields.map((field, index) => (
        <div key={index} className='my-2'>
          <input
            type='text'
            placeholder='Twitter Username'
            className='w-full bg-white border border-gray-300 rounded-lg py-2 px-4 text-gray-700 focus:border-blue-400 focus:outline-none'
            value={field}
            onChange={(e) => handleChange(e, index)}
          />
        </div>
      ))}
      <div className='my-2 flex flex-row justify-end gap-1'>
        {fields.length > 1 && <Button onClick={handleRemove}>-</Button>}
        {fields.length < 10 && (
          <Button onClick={handleAdd} className='bg-blue-500 text-white px-4 py-2 rounded'>
            +
          </Button>
        )}
      </div>
      <Button onClick={handleSubmit} isLoading={isLoading}>
        <span>Save</span>
      </Button>
    </div>
  );
}

This component takes care of adding the logged in user’s favUsers array to state, and displaying that in information in a set of input components.

The only thing missing from it is to add our updateAccount action we just defined earlier. So at the top of the file, let’s import it and add the logic to our InputFields submit handler

import updateAccount from '@wasp/actions/updateAccount'; // <--- add this import

//...

const handleSubmit = async () => { // < --- add this function
    try {
      setIsLoading(true);
      await updateAccount({ favUsers: fields });
    } catch (err: any) {
      alert(err.message);
    } finally {
      setIsLoading(false);
    }
  };

Also, in your AccountPage make sure to replace the line {JSON.stringify(user, null, 2)} with the newly created component <InputFields user={user} />.

Here is what the entire AccountPage.tsx file should now look like in case you get stuck:

import Button from './Button';
import { ChangeEvent, useEffect, useState } from 'react';
import logout from '@wasp/auth/logout';
import type { User } from '@wasp/entities';
import updateAccount from '@wasp/actions/updateAccount'

const AccountPage = ({ user }: { user: User }) => {
  return (
    <div className='flex flex-col justify-center items-center mt-12 w-full'>
      <div className='flex flex-col items-center justify-center gap-4 border border-neutral-700 bg-neutral-100/40 rounded-xl p-1 sm:p-4 w-full'>
        <div className='flex flex-row justify-end w-full px-4 pt-2'>
          <Button onClick={logout}>Logout</Button>
        </div>
        <InputFields user={user} />
      </div>
    </div>
  );
};

export default AccountPage;

function InputFields({ user }: { user: User }) {
  const [isLoading, setIsLoading] = useState(false);
  const [fields, setFields] = useState(['']);

  useEffect(() => {
    if (user?.favUsers.length > 0) {
      setFields(user.favUsers);
    }
  }, [user?.favUsers]);

  const handleAdd = () => {
    setFields([...fields, '']);
  };

  const handleRemove = () => {
    const newFields = [...fields];
    newFields.splice(fields.length - 1, 1);
    setFields(newFields);
  };

  const handleChange = (e: ChangeEvent<HTMLInputElement>, index: number) => {
    const newFields = [...fields];
    newFields[index] = e.target.value;
    setFields(newFields);
  };

  const handleSubmit = async () => {
    try {
      setIsLoading(true);
      await updateAccount({ favUsers: fields });
    } catch (err: any) {
      alert(err.message);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div className='w-full p-4'>
      <div className='flex flex-row justify-start items-start'>
        <h2 className='ml-1 font-bold'>Trend-Setting Twitter Accounts</h2>
      </div>
      {fields.map((field, index) => (
        <div key={index} className='my-2'>
          <input
            type='text'
            placeholder='Twitter Username'
            className='w-full bg-white border border-gray-300 rounded-lg py-2 px-4 text-gray-700 focus:border-blue-400 focus:outline-none'
            value={field}
            onChange={(e) => handleChange(e, index)}
          />
        </div>
      ))}
      <div className='my-2 flex flex-row justify-end gap-1'>
        {fields.length > 1 && <Button onClick={handleRemove}>-</Button>}
        {fields.length < 10 && (
          <Button onClick={handleAdd} className='bg-blue-500 text-white px-4 py-2 rounded'>
            +
          </Button>
        )}
      </div>
      <Button onClick={handleSubmit} isLoading={isLoading}>
        <span>Save</span>
      </Button>
    </div>
  );
}

And here’s what your AccountPage should look like when navigating to localhost:3000/account (note: the styling may be a bit ugly, but we’ll take care of that later):

Untitled

Fantastic. So we’ve got the majority of the app logic finished — our own personal twitter “intern” to help us all become thought leaders and thread bois 🤣.

Adding a Cron Job​

But wouldn’t it be cool if we could automate the Generate New Ideas process? Each time you click the button, it takes quite a while for tweets to be scraped, and ideas to be generated, especially if we are generating ideas for a lot of new tweets.

So it would be nicer if we had a cron job (recurring task), that ran automatically in the background at a set interval.

With Wasp, that’s also super easy to set up. To do so, let’s go to our main.wasp file and add our job at the very bottom:

//...

job newIdeasJob {
  executor: PgBoss,
  perform: {
    fn: import generateNewIdeasWorker from "@server/worker/generateNewIdeasWorker.js"
  },
  entities: [User, GeneratedIdea, Tweet, TweetDraft],
  schedule: {
    // run cron job every 30 minutes
    cron: "*/30 * * * *",
    executorOptions: {
      pgBoss: {=json { "retryLimit": 2 } json=},
    }
  }
}

Let’s run through the code above:

  • Jobs use pg-boss, a postgres extension, to queue and run tasks under the hood.
  • with perform we’re telling the job what function we want it to call: generateNewIdeasWorker
  • just like actions and queries, we have to tell the job which entities we want to give it access to. In this case, we will need access to all of our entities.
  • the schedule allows us to pass some options to pg-boss so that we can make it a recurring task. In this case, I set it to run every 30 minutes, but you can set it to any interval you’d like (tip: change the comment and let github co-pilot write the cron for you). We also tell pg-boss to retry a failed job two times.

Perfect. So now, our app will automatically scrape our favorite users’ tweets and generate new ideas for us every 30 minutes. This way, if we revisit the app after a few days, all the content will already be there and we won’t have to wait a long time for it to generate it for us. We also make sure we never miss out on generating ideas for older tweets.

But for that to happen, we have to define the function our job will call. To do this, create a new directory worker within the server folder, and within it a new file: src/server/worker/generateNewIdeasWorker

import { generateNewIdeas } from '../ideas.js';

export default async function generateNewIdeasWorker(_args: unknown, context: any) {
  try {
    console.log('Running recurring task: generateNewIdeasWorker')
    const allUsers = await context.entities.User.findMany({});

    for (const user of allUsers) {
      context.user = user;
      console.log('Generating new ideas for user: ', user.username);
      await generateNewIdeas(undefined as never, context);
      console.log('Done generating new ideas for user: ', user.username)
    }

  } catch (error: any) {
    console.log('Recurring task error: ', error);
  }
}

In this file, all we’re doing is looping through all the users in our database, and passing them via the context object to our generateNewIdeas action. The nice thing about jobs is that Wasp automatically passes the context object to these functions, which we can then pass along to our action.

So now, at the interval that you set (e.g. 30 minutes), you should notice the logs being printed to the console whenever your job starts automatically running.

[Server]  Generating new ideas for user:  vinny

Alright, things are looking pretty good now, but let’s not forget to add a page to view all the notes we added and embedded to our vector store!

Adding a Notes Page​

Go ahead and add the following route to your main.wasp file:

route NotesPage { path: "/notes", to: NotesPage }
page NotesPage {
  authRequired: true,
  component: import Notes from "@client/NotesPage"
}

Create the complementary page, src/client/NotesPage.tsx and add the following boilerplate just to get started (we’ll add the rest later):

const NotesPage = () => {

  return (
    <>Notes</>
  );
};

export default NotesPage;

It would be nice if we had a simple Nav Bar to navigate back and forth between our two pages. It would also be cool if we had our <AddNote /> input component on all pages, that way it’s easy for us to add an idea whenever inspiration strikes.

Rather than copying the NavBar and AddNote code to both pages, let’s create a wrapper, or “root”, component for our entire app so that all of our pages have the same Nav Bar and layout.

To do that, in our main.wasp file, let’s define our root component by adding a client property to our app configuration at the very top of the file. This is how the entire app object should look like now:

app twitterAgent {
  wasp: {
    version: "^0.10.6"
  },
  title: "twitter-agent",
  client: { 
    rootComponent: import App from "@client/App",
  },
  db: { 
    system: PostgreSQL,
  },
  auth: {
    userEntity: User,
    onAuthFailedRedirectTo: "/login",
    methods: {
      usernameAndPassword: {},
    }
  },
  dependencies: [
    ("openai", "3.2.1"),
    ("rettiwt-api", "1.1.8"),
    ("langchain", "0.0.91"),
    ("@pinecone-database/pinecone", "0.1.6"),
    ("@headlessui/react", "1.7.15"),
    ("react-icons", "4.8.0"),
    ("react-twitter-embed", "4.0.4")
  ],
}

// entities, operations, routes, and other stuff...

Next, create a new file src/client/App.tsx with the following content:

import './Main.css';
import AddNote from './AddNote';
import { ReactNode } from 'react';
import useAuth from '@wasp/auth/useAuth';

const App = ({ children }: { children: ReactNode }) => {

  const { data: user } = useAuth();

  return (
    <div className='min-h-screen bg-neutral-300/70 text-center'>
      <div className='flex flex-col gap-6 justify-center items-center mx-auto pt-12'>
        <div className='flex flex-row justify-between items-center w-1/2 mb-6 text-neutral-600 px-2'>
          <div className='flex justify-start w-1/3'>
            <a href='/' className='hover:underline cursor-pointer'>
              🤖 Generated Ideas
            </a>
          </div>
          <div className='flex justify-center w-1/3'>
            <a href='/notes' className='hover:underline cursor-pointer'>
              📝 My Notes
            </a>
          </div>
          <div className='flex justify-end w-1/3'>
            <a href='/account' className='hover:underline cursor-pointer'>
              👤 Account
            </a>
          </div>
        </div>

        <div className='flex flex-col gap-4 justify-center items-center w-2/4'>
          {!!user && <AddNote />}
          <hr className='border border-t-1 border-neutral-100/70 w-full' />
          {children}
        </div>
      </div>
    </div>
  );
};

export default App;

With this defined, Wasp will know to pass all other routes as children through our App component. That way, we will always show the Nav Bar and AddNote component on the top of every page.

We also take advantage of Wasp’s handy useAuth hook to check if a user is logged in, and if so we show the AddNote component.

Now, we can delete the duplicate code on our MainPage. This is what it should look like now:

import { useState } from 'react';
import generateNewIdeas from '@wasp/actions/generateNewIdeas';
import { useQuery } from '@wasp/queries';
import getTweetDraftsWithIdeas from '@wasp/queries/getTweetDraftsWithIdeas';
import Button from './Button';
import { TwitterTweetEmbed } from 'react-twitter-embed';

const MainPage = () => {
  const [isGenerating, setIsGenerating] = useState(false);

  const {
    data: tweetDrafts,
    isLoading: isTweetDraftsLoading,
    error: tweetDraftsError,
  } = useQuery(getTweetDraftsWithIdeas);

  const handleNewIdeas = async (e: any) => {
    try {
      setIsGenerating(true);
      await generateNewIdeas();
    } catch (error: any) {
      alert(error.message);
    } finally {
      setIsGenerating(false);
    }
  };

  if (isTweetDraftsLoading) {
    return 'Loading...';
  }

  if (tweetDraftsError) {
    return 'Error: ' + tweetDraftsError.message;
  }

  return (
    <>
      <div className='flex flex-row justify-center w-full'>
        <Button onClick={handleNewIdeas} isLoading={isGenerating}>
          Generate New Ideas
        </Button>
      </div>
      <div className='flex flex-col gap-4 justify-center items-center w-full'>
        {tweetDrafts.map((tweetDraft) => (
          <>
            <h2 className='text-2xl font-bold'>Generated Ideas</h2>
            <div key={tweetDraft.id} className='flex flex-col gap-2 justify-center items-center w-full'>
              <h2>Original Tweet</h2>
              <div className='flex flex-row gap-2 justify-center items-center w-full'>
                <TwitterTweetEmbed tweetId={tweetDraft.originalTweet.tweetId} />
              </div>
              <h2>Tweet Draft</h2>
              <div className='flex flex-row gap-2 justify-center items-center w-full'>
                <div className='w-full p-4 h-22 bg-blue-100 border rounded-lg w-full'>{tweetDraft.content}</div>
              </div>

              {!!tweetDraft.notes && tweetDraft.notes !== tweetDraft.originalTweet.content && (
                <>
                  <h2>Your Similar Notes</h2>
                  {tweetDraft.notes}
                </>
              )}
              <div className='flex flex-col gap-2 justify-center items-center w-full'>
                <h2>Ideas</h2>
                {tweetDraft.originalTweet.ideas.map((idea) => (
                  <div key={idea.id} className='flex flex-row gap-2 justify-center items-center w-full'>
                    <div className='flex flex-row gap-2 justify-center items-center w-full'>
                      <div className='w-full p-4 h-22 bg-neutral-100 border rounded-lg w-full'>{idea.content}</div>
                    </div>
                  </div>
                ))}
              </div>
            </div>
          </>
        ))}
      </div>
    </>
  );
};
export default MainPage;

Next, we need to create a query that allows us to fetch all of our added notes and ideas that have been embedded in our vector store.

For that, we need to define a new query in our main.wasp file:

query getEmbeddedNotes {
  fn: import { getEmbeddedNotes } from "@server/ideas.js",
  entities: [GeneratedIdea]
}

We then need to create that query at the bottom of our src/actions/ideas.ts file:

// first import the type at the top of the file
import type { GetEmbeddedNotes, GetTweetDraftsWithIdeas } from '@wasp/queries/types';

//...

export const getEmbeddedNotes: GetEmbeddedNotes<never, GeneratedIdea[]> = async (_args, context) => {
  if (!context.user) {
    throw new HttpError(401, 'User is not authorized');
  }

  const notes = await context.entities.GeneratedIdea.findMany({
    where: {
      userId: context.user.id,
      isEmbedded: true,
    },
        orderBy: {
      createdAt: 'desc',
    },
  });

  return notes;
}

Now let’s go back to our src/client/NotesPage.tsx and add our query. Our new file will look like this:

import { useQuery } from '@wasp/queries';
import getEmbeddedNotes from '@wasp/queries/getEmbeddedNotes';

const NotesPage = () => {
  const { data: notes, isLoading, error } = useQuery(getEmbeddedNotes);

  if (isLoading) <div>Loading...</div>;
  if (error) <div>Error: {error.message}</div>;

  return (
    <>
      <h2 className='text-2xl font-bold'>My Notes</h2>
      {notes && notes.length > 0 ? (
        notes.map((note) => (
          <div key={note.id} className='flex flex-col gap-2 justify-center items-center w-full'>
            <div className='flex flex-row gap-2 justify-center items-center w-full'>
              <div className='w-full p-4 h-22 bg-blue-100 border rounded-lg w-full'>{note.content}</div>
            </div>
          </div>
        ))
      ) : notes && notes.length === 0 && (
        <div className='flex flex-col gap-2 justify-center items-center w-full'>
          <div className='w-full p-4 h-22 bg-blue-100 border rounded-lg w-full'>No notes yet</div>
        </div>
      )}
    </>
  );
};

export default NotesPage;

Cool! Now we should be fetching all our embedded notes and ideas, signified by the isEmbedded tag in our postgres database. Your Notes page should now look something like this:

Untitled

You Did it! Your own Twitter Intern 🤖​

Help me help you

🌟 If you haven’t yet, please star us on GitHub, especially if you found this useful! If you do, it helps support us in creating more content like this. And if you don’t… well, we will deal with it, I guess.

https://media.giphy.com/media/3oEjHEmvj6yScz914s/giphy.gif

And that’s it! You’ve now got yourself a semi-autonomous twitter brainstorming agent to help inspire new ideas and keep you actively contributing 🚀

There’s way more you can do with these tools, but this is a great start.

Remember, if you want to see a more advanced version of this app which utilizes the official Twitter API to send tweets, gives you the ability to edit and add generated notes on the fly, has manual similarity search for all your notes, and more, then you can check out the 💥 Banger Tweet Bot 🤖.

And, once again, here's the repo for the finished app we built in this tutorial: Personal Twitter Intern

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/06/28/what-can-you-build-with-wasp.html b/blog/2023/06/28/what-can-you-build-with-wasp.html index 5654661c1a..8c85a69de2 100644 --- a/blog/2023/06/28/what-can-you-build-with-wasp.html +++ b/blog/2023/06/28/what-can-you-build-with-wasp.html @@ -19,13 +19,13 @@ - - + + -
-

What can you build with Wasp?

· 4 min read
Matija Sosic

Launch Week 3 is coming

Welcome to the 3rd day of our Launch Week #3 - Community Day! Our community is the most important aspect of everything we do at Wasp, and we believe it's only right to have a day dedicated to it.

We'll showcase some of the coolest project built with Wasp so far and through that explore together what kind of apps you can develop with it. Let's dive in!

tip

If you're looking for a quick way to start your project, check out our Ultimate SaaS Starter. It packs Tailwind, GPT, Stripe ane other popular integrations, all pre-configured for you.

CoverLetterGPT.xyz - GPT-powered cover letter generator​

Try it out: coverlettergpt.xyz

Source code: https://github.com/vincanger/coverlettergpt

Wasp features used: Social login with Google + auth UI, email sending

UI Framework: Chakra UI

Created in the midst of a GPT craze, this is one of the most popular Wasp apps so far! It does exactly what it says on a tin - given job description and your CV, it generates a unique cover letter customized for you. It does that via parsing your CV and feeding it together with the job description to the GPT api, along with the additional settings such as creativity level (careful with that one!).

Although it started as a fun side project, it seems that people actually find it useful, at least as a starting point for writing your own cover letter. CoverLetterGPT has been used to generate close to 5,000 cover letters!

Try it out and have fun or use it as an inspiration for your next project!

Amicus.work - most "enterprise SaaS" app 👔 💼​

Try it out: amicus.work

Wasp features used: Authentication, email sending, async/cron jobs

UI Framework: Material UI

This app really gives away those "enterprise SaaS" vibes - when you see it you know it means some serious business! The author describes it as "Asana for you lawyers" (you can read how the author got first customers for it here), or as an easy way for lawyers to manage and collaborate on their workflows.

File upload, workflow creation, calendar integration, collaboration - this app has it all! Amicus might be the most advanced project made with Wasp so far. Erlis startedbuilding it even with Wasp still in Alpha, and it has withstood the test of time since then.

Description Generator - GPT-powered product description generator - first acquired app made with Wasp! 💰💰​

Try it out: description-generator.online

Wasp features used: Social login with Google + auth UI

UI Framework: Chakra UI

Another SaaS that uses GPT integration to cast its magic! Given product name and instructions on what kind of content you'd like to get, this app generates the professionaly written product listing. It's a perfect fit for marketplace owners that want to present their products in the best light but don't have a budget for the marketing agency.

What's special about Description Generator is that it was recently sold , making it the first Wasp-powered project that got acquired! Stay tuned, as the whole story is coming soon.

TweetBot - your personal Twitter intern! 🐦🤖​

Try it out: banger-tweet-bot.netlify.app

Source code: https://github.com/vincanger/banger-tweet-bot

Wasp features used:Authentication, async/cron jobs

UI Framework: Tailwind

The latest and greatest from Vince's lab - an app that serves as your personal twitter brainstorming agent! It takes your raw ideas as an input, monitors current twitter trends (from the accounts you selected) and helps you brainstorm new tweets and also drafts them for you!

While the previously mentioned projects queried the GPT API directly, TweetBot makes use of the LangChain library, which does a lot of heavy lifting for you, allowing you to produce bigger prompts and preserve the context between subsequent queries.

Summary​

As you could see above, Wasp can be used to build pretty much any database-backed web application! It is especially well suited for so called "workflow-based" applications where you typically have a bunch of resources (e.g. your tasks, or tweets) that you want to manipulate in some way.

With our built-in deployment support (e.g. you can deploy to Fly.io for free with a single CLI command) the whole development process is extremely streamlined.

We can't wait to see what you build next!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

What can you build with Wasp?

· 4 min read
Matija Sosic

Launch Week 3 is coming

Welcome to the 3rd day of our Launch Week #3 - Community Day! Our community is the most important aspect of everything we do at Wasp, and we believe it's only right to have a day dedicated to it.

We'll showcase some of the coolest project built with Wasp so far and through that explore together what kind of apps you can develop with it. Let's dive in!

tip

If you're looking for a quick way to start your project, check out our Ultimate SaaS Starter. It packs Tailwind, GPT, Stripe ane other popular integrations, all pre-configured for you.

CoverLetterGPT.xyz - GPT-powered cover letter generator​

Try it out: coverlettergpt.xyz

Source code: https://github.com/vincanger/coverlettergpt

Wasp features used: Social login with Google + auth UI, email sending

UI Framework: Chakra UI

Created in the midst of a GPT craze, this is one of the most popular Wasp apps so far! It does exactly what it says on a tin - given job description and your CV, it generates a unique cover letter customized for you. It does that via parsing your CV and feeding it together with the job description to the GPT api, along with the additional settings such as creativity level (careful with that one!).

Although it started as a fun side project, it seems that people actually find it useful, at least as a starting point for writing your own cover letter. CoverLetterGPT has been used to generate close to 5,000 cover letters!

Try it out and have fun or use it as an inspiration for your next project!

Amicus.work - most "enterprise SaaS" app 👔 💼​

Try it out: amicus.work

Wasp features used: Authentication, email sending, async/cron jobs

UI Framework: Material UI

This app really gives away those "enterprise SaaS" vibes - when you see it you know it means some serious business! The author describes it as "Asana for you lawyers" (you can read how the author got first customers for it here), or as an easy way for lawyers to manage and collaborate on their workflows.

File upload, workflow creation, calendar integration, collaboration - this app has it all! Amicus might be the most advanced project made with Wasp so far. Erlis startedbuilding it even with Wasp still in Alpha, and it has withstood the test of time since then.

Description Generator - GPT-powered product description generator - first acquired app made with Wasp! 💰💰​

Try it out: description-generator.online

Wasp features used: Social login with Google + auth UI

UI Framework: Chakra UI

Another SaaS that uses GPT integration to cast its magic! Given product name and instructions on what kind of content you'd like to get, this app generates the professionaly written product listing. It's a perfect fit for marketplace owners that want to present their products in the best light but don't have a budget for the marketing agency.

What's special about Description Generator is that it was recently sold , making it the first Wasp-powered project that got acquired! Stay tuned, as the whole story is coming soon.

TweetBot - your personal Twitter intern! 🐦🤖​

Try it out: banger-tweet-bot.netlify.app

Source code: https://github.com/vincanger/banger-tweet-bot

Wasp features used:Authentication, async/cron jobs

UI Framework: Tailwind

The latest and greatest from Vince's lab - an app that serves as your personal twitter brainstorming agent! It takes your raw ideas as an input, monitors current twitter trends (from the accounts you selected) and helps you brainstorm new tweets and also drafts them for you!

While the previously mentioned projects queried the GPT API directly, TweetBot makes use of the LangChain library, which does a lot of heavy lifting for you, allowing you to produce bigger prompts and preserve the context between subsequent queries.

Summary​

As you could see above, Wasp can be used to build pretty much any database-backed web application! It is especially well suited for so called "workflow-based" applications where you typically have a bunch of resources (e.g. your tasks, or tweets) that you want to manipulate in some way.

With our built-in deployment support (e.g. you can deploy to Fly.io for free with a single CLI command) the whole development process is extremely streamlined.

We can't wait to see what you build next!

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/06/29/new-wasp-lsp.html b/blog/2023/06/29/new-wasp-lsp.html index 4cb8807833..7ba7e994b6 100644 --- a/blog/2023/06/29/new-wasp-lsp.html +++ b/blog/2023/06/29/new-wasp-lsp.html @@ -19,13 +19,13 @@ - - + + -
-

Wasp LSP 2.0 - Next-level autocompletion and IDE integration for Wasp projects!

· 2 min read
Matija Sosic

It's the fourth day of our Launch Week #3 - today it's all about dev tooling and making sure that the time you spend looking at your IDE is as pleasurable as possible!

We present the next generation of Wasp LSP (Language Server Protocol) implementation for VS Code! As you might already know, Wasp has its own simple configuration language (.wasp) that acts as a glue between your React & Node.js code.

Although it's a very simple, declarative language (you can think of it as a bit nicer/smarter JSON), and having it allows us to completely tailor the developer experience (aka get rid of boilerplate), it also means we have to provide our own tooling for it (syntax highlighting, auto completion, ...).

We started with syntax highlighting, then basic autocompletion and snippet support, but now we really took things to the next level! Writing Wasp code now is much closer to what we had in our mind when envisioning Wasp.

Without further ado, here's what's new:

✨ Autocompletion for config object properties (auth, webSocket, ...)​

Until now, Wasp offered autocompletion only for the top-level declarations such as page or app. Now, it works for any (sub)-property (as one would expect 😅)!

Fill out your Wasp configuration faster and with less typos! 💻🚀

🔍 Type Hints​

Opening documentation takes you out of your editor and out of your flow. Stay in the zone with in-editor type hints! 💡

🚨 Import Diagnostics​

Keep tabs on what's left to implement with JS import diagnostics! There's nothing more satisfying than watching those errors vanish. 😌

Wasp now automatically detects if the function you referenced doesn't exist or is not exported.

🔗 Goto Definition​

Your Wasp file is the central hub of your project. Easily navigate your code with goto definition and make changes in a snap! 💨

Cmd/Ctrl + click and Wasp LSP takes you straight to the function body!

Don't forget to install Wasp VS Code extension and we wish you happy coding! You can get started right away and try it out here.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

- - +
+

Wasp LSP 2.0 - Next-level autocompletion and IDE integration for Wasp projects!

· 2 min read
Matija Sosic

It's the fourth day of our Launch Week #3 - today it's all about dev tooling and making sure that the time you spend looking at your IDE is as pleasurable as possible!

We present the next generation of Wasp LSP (Language Server Protocol) implementation for VS Code! As you might already know, Wasp has its own simple configuration language (.wasp) that acts as a glue between your React & Node.js code.

Although it's a very simple, declarative language (you can think of it as a bit nicer/smarter JSON), and having it allows us to completely tailor the developer experience (aka get rid of boilerplate), it also means we have to provide our own tooling for it (syntax highlighting, auto completion, ...).

We started with syntax highlighting, then basic autocompletion and snippet support, but now we really took things to the next level! Writing Wasp code now is much closer to what we had in our mind when envisioning Wasp.

Without further ado, here's what's new:

✨ Autocompletion for config object properties (auth, webSocket, ...)​

Until now, Wasp offered autocompletion only for the top-level declarations such as page or app. Now, it works for any (sub)-property (as one would expect 😅)!

Fill out your Wasp configuration faster and with less typos! 💻🚀

🔍 Type Hints​

Opening documentation takes you out of your editor and out of your flow. Stay in the zone with in-editor type hints! 💡

🚨 Import Diagnostics​

Keep tabs on what's left to implement with JS import diagnostics! There's nothing more satisfying than watching those errors vanish. 😌

Wasp now automatically detects if the function you referenced doesn't exist or is not exported.

🔗 Goto Definition​

Your Wasp file is the central hub of your project. Easily navigate your code with goto definition and make changes in a snap! 💨

Cmd/Ctrl + click and Wasp LSP takes you straight to the function body!

Don't forget to install Wasp VS Code extension and we wish you happy coding! You can get started right away and try it out here.

Discord

Join our developer community

Wasp is 100% open source. Join our Discord to learn from others and get help whenever you need it!

Join our Discord 👾
→
📫

Subscribe to our newsletter

Once per month - receive useful blog posts and Wasp news.

+ + \ No newline at end of file diff --git a/blog/2023/06/30/tutorial-jam.html b/blog/2023/06/30/tutorial-jam.html index 7128d59eb6..05440b8840 100644 --- a/blog/2023/06/30/tutorial-jam.html +++ b/blog/2023/06/30/tutorial-jam.html @@ -19,15 +19,15 @@ - - + + -
-

Tutorial Jam #1 - Teach Others & Win Prizes!

· 4 min read
Vinny

Introduction​

The Wasp Tutorial Jam is a contest where participants are required to create a tutorial about building a fullstack React/Node app with Wasp.

Wait, What’s Wasp?​

First of all, it’s sad that you’ve never heard of Wasp.

https://media0.giphy.com/media/kr5PszPQawIRq/giphy.gif?cid=7941fdc6gwgjf866b0akslgciedh53jf9narttadkglvvcp0&ep=v1_gifs_search&rid=giphy.gif&ct=g

Wasp is a unique fullstack framework for building React/NodeJS/Prisma/Tanstack Query apps.

Because it’s based on a compiler, you write a simple config file, and Wasp can take care of generating the skeleton of your app for you (and regenerating when the config file changes). You can read more about Wasp here

Rules​

The rules are simple. The tutorial must:

Using an external auth method?

If your app is using an external authentication method(s) supported by Wasp (such as Google or GitHub), make sure to additionally set the necessary environment variables specifically required by these method(s).

While these are the general instructions on deploying the server anywhere, we also have more detailed instructions for chosen providers below, so check that out for more guidance if you are deploying to one of those providers.

3. Deploying the Web Client (frontend)​

To build the web app, position yourself in .wasp/build/web-app directory:

cd .wasp/build/web-app

Run

npm install && REACT_APP_API_URL=<url_to_wasp_backend> npm run build

where <url_to_wasp_backend> is the URL of the Wasp server that you previously deployed.

The command above will build the web client and put it in the build/ directory in the web-app directory.

Since the app's frontend is just a bunch of static files, you can deploy it to any static hosting provider.

4. Deploying the Database​

Any PostgreSQL database will do, as long as you provide the server with the correct DATABASE_URL env var and ensure that the database is accessible from the server.

Different Providers​

We'll cover a few different deployment providers below:

  • Fly.io (server and database)
  • Netlify (client)
  • Railway (server, client and database)
  • Heroku (server and database)

Fly.io (server and database)​

We will show how to deploy the server and provision a database for it on Fly.io.

We automated this process for you

If you want to do all of the work below with one command, you can use the Wasp CLI.

Wasp CLI deploys the server, deploys the client, and sets up a database. It also gives you a way to redeploy (update) your app with a single command.

Fly.io offers a variety of free services that are perfect for deploying your first Wasp app! You will need a Fly.io account and the flyctl CLI.

note

Fly.io offers support for both locally built Docker containers and remotely built ones. However, for simplicity and reproducibility, we will default to the use of a remote Fly.io builder.

Additionally, fly is a symlink for flyctl on most systems and they can be used interchangeably.

Make sure you are logged in with flyctl CLI. You can check if you are logged in with flyctl auth whoami, and if you are not, you can log in with flyctl auth login.

Set Up a Fly.io App​

info

You need to do this only once per Wasp app.

Unless you already have a Fly.io app that you want to deploy to, let's create a new Fly.io app.

After you have built the app, position yourself in .wasp/build/ directory:

cd .wasp/build

Next, run the launch command to set up a new app and create a fly.toml file:

flyctl launch --remote-only

This will ask you a series of questions, such as asking you to choose a region and whether you'd like a database.

  • Say yes to Would you like to set up a Postgresql database now? and select Development. Fly.io will set a DATABASE_URL for you.

  • Say no to Would you like to deploy now? (and to any additional questions).

    We still need to set up several environment variables.

What if the database setup fails?

If your attempts to initiate a new app fail for whatever reason, then you should run flyctl apps destroy <app-name> before trying again. Fly does not allow you to create multiple apps with the same name.

What does it look like when your DB is deployed correctly?

When your DB is deployed correctly, you'll see it in the Fly.io dashboard:

image

Next, let's copy the fly.toml file up to our Wasp project dir for safekeeping.

cp fly.toml ../../

Next, let's add a few more environment variables:

flyctl secrets set PORT=8080
flyctl secrets set JWT_SECRET=<random_string_at_least_32_characters_long>
flyctl secrets set WASP_WEB_CLIENT_URL=<url_of_where_frontend_will_be_deployed>
note

If you do not know what your frontend URL is yet, don't worry. You can set WASP_WEB_CLIENT_URL after you deploy your frontend.

Using an external auth method?

If your app is using an external authentication method(s) supported by Wasp (such as Google or GitHub), make sure to additionally set the necessary environment variables specifically required by these method(s).

If you want to make sure you've added your secrets correctly, run flyctl secrets list in the terminal. Note that you will see hashed versions of your secrets to protect your sensitive data.

Deploy to a Fly.io App​

While still in the .wasp/build/ directory, run:

flyctl deploy --remote-only --config ../../fly.toml

This will build and deploy the backend of your Wasp app on Fly.io to https://<app-name>.fly.dev 🤘🎸

Now, if you haven't, you can deploy your frontend and add the client url by running flyctl secrets set WASP_WEB_CLIENT_URL=<url_of_deployed_frontend>. We suggest using Netlify for your frontend, but you can use any static hosting provider.

Additionally, some useful flyctl commands:

flyctl logs
flyctl secrets list
flyctl ssh console

Redeploying After Wasp Builds​

When you rebuild your Wasp app (with wasp build), it will remove your .wasp/build/ directory. In there, you may have a fly.toml from any prior Fly.io deployments.

While we will improve this process in the future, in the meantime, you have a few options:

  1. Copy the fly.toml file to a versioned directory, like your Wasp project dir.

    From there, you can reference it in flyctl deploy --config <path> commands, like above.

  2. Backup the fly.toml file somewhere before running wasp build, and copy it into .wasp/build/ after.

    When the fly.toml file exists in .wasp/build/ dir, you do not need to specify the --config <path>.

  3. Run flyctl config save -a <app-name> to regenerate the fly.toml file from the remote state stored in Fly.io.

Netlify (client)​

We'll show how to deploy the client on Netlify.

Netlify is a static hosting solution that is free for many use cases. You will need a Netlify account and Netlify CLI installed to follow these instructions.

Make sure you are logged in with Netlify CLI. You can check if you are logged in with netlify status, and if you are not, you can log in with netlify login.

First, make sure you have built the Wasp app. We'll build the client web app next.

To build the web app, position yourself in .wasp/build/web-app directory:

cd .wasp/build/web-app

Run

npm install && REACT_APP_API_URL=<url_to_wasp_backend> npm run build

where <url_to_wasp_backend> is the URL of the Wasp server that you previously deployed.

We can now deploy the client with:

netlify deploy

Carefully follow the instructions i.e. do you want to create a new app or use an existing one, the team under which your app will reside etc.

The final step is to run:

netlify deploy --prod`

That is it! Your client should be live at https://<app-name>.netlify.app ✨

note

Make sure you set this URL as the WASP_WEB_CLIENT_URL environment variable in your server hosting environment (e.g., Fly.io or Heroku).

Railway (server, client and database)​

We will show how to deploy the client, the server, and provision a database on Railway.

Railway is a simple and great way to host your server and database. It's also possible to deploy your entire app: database, server, and client. You can use the platform for free for a limited time, or if you meet certain eligibility requirements. See their plans page for more info.

Prerequisites​

To get started, follow these steps:

  1. Make sure your Wasp app is built by running wasp build in the project dir.

  2. Create a Railway account

    Free Tier

    Sign up with your GitHub account to be eligible for the free tier

  3. Install the Railway CLI

  4. Run railway login and a browser tab will open to authenticate you.

Create New Project​

Let's create our Railway project:

  1. Go to your Railway dashboard, click on New Project, and select Provision PostgreSQL from the dropdown menu.
  2. Once it initializes, right-click on the New button in the top right corner and select Empty Service.
  3. Once it initializes, click on it, go to Settings > General and change the name to server
  4. Go ahead and create another empty service and name it client

Changing the name

Deploy Your App to Railway​

Setup Domains​

We'll need the domains for both the server and client services:

  1. Go to the server instance's Settings tab, and click Generate Domain.
  2. Do the same under the client's Settings.

Copy the domains as we will need them later.

Deploying the Server​

Let's deploy our server first:

  1. Move into your app's .wasp/build/ directory:

    cd .wasp/build

  2. Link your app build to your newly created Railway project:

    railway link

  3. Go into the Railway dashboard and set up the required env variables:

    Open the Settings and go to the Variables tab:

    • click Variable reference and select DATABASE_URL (it will populate it with the correct value)

    • add WASP_WEB_CLIENT_URL - enter the the client domain (e.g. https://client-production-XXXX.up.railway.app)

    • add JWT_SECRET - enter a random string at least 32 characters long (use an online generator)

      Using an external auth method?

      If your app is using an external authentication method(s) supported by Wasp (such as Google or GitHub), make sure to additionally set the necessary environment variables specifically required by these method(s).

  4. Push and deploy the project:

railway up

Select server when prompted with Select Service.

Railway will now locate the Dockerfile and deploy your server 👍

Deploying the Client​

  1. Next, change into your app's frontend build directory .wasp/build/web-app:

    cd web-app

  2. Create the production build, using the server domain as the REACT_APP_API_URL:

    npm install && REACT_APP_API_URL=<url_to_wasp_backend> npm run build

  3. Next, we want to link this specific frontend directory to our project as well:

    railway link

  4. We need to configure Railway's static hosting for our client.

    Setting Up Static Hosting

    Copy the build folder within the web-app directory to dist:

    cp -r build dist

    We'll need to create the following files:

    • Dockerfile with:

      Dockerfile
      FROM pierrezemb/gostatic
      CMD [ "-fallback", "index.html" ]
      COPY ./dist/ /srv/http/

    • .dockerignore with:

      .dockerignore
      node_modules/

    You'll need to repeat these steps each time you run wasp build as it will remove the .wasp/build/web-app directory.

    Here's a useful shell script to do the process

    If you want to automate the process, save the following as deploy_client.sh in the root of your project:

    deploy_client.sh
    #!/usr/bin/env bash

    if [ -z "$REACT_APP_API_URL" ]
    then
      echo "REACT_APP_API_URL is not set"
      exit 1
    fi

    wasp build
    cd .wasp/build/web-app

    npm install && REACT_APP_API_URL=$REACT_APP_API_URL npm run build

    cp -r build dist

    dockerfile_contents=$(cat <<EOF
    FROM pierrezemb/gostatic
    CMD [ "-fallback", "index.html" ]
    COPY ./dist/ /srv/http/
    EOF
    )

    dockerignore_contents=$(cat <<EOF
    node_modules/
    EOF
    )

    echo "$dockerfile_contents" > Dockerfile
    echo "$dockerignore_contents" > .dockerignore

    railway up

    Make it executable with:

    chmod +x deploy_client.sh

    You can run it with:

    REACT_APP_API_URL=<url_to_wasp_backend> ./deploy_client.sh

  5. Set the PORT environment variable to 8043 under the Variables tab.

  6. Deploy the client and select client when prompted with Select Service:

railway up

Conclusion​

And now your Wasp should be deployed! 🐝 🚂 🚀

Back in your Railway dashboard, click on your project and you should see your newly deployed services: Postgres, Server, and Client.

Updates & Redeploying​

When you make updates and need to redeploy:

  • run wasp build to rebuild your app
  • run railway up in the .wasp/build directory (server)
  • repeat all the steps in the .wasp/build/web-app directory (client)

Heroku (server and database)​

We will show how to deploy the server and provision a database for it on Heroku.

note

Heroku used to offer free apps under certain limits. However, as of November 28, 2022, they ended support for their free tier. https://blog.heroku.com/next-chapter

As such, we recommend using an alternative provider like Fly.io for your first apps.

You will need Heroku account, heroku CLI and docker CLI installed to follow these instructions.

Make sure you are logged in with heroku CLI. You can check if you are logged in with heroku whoami, and if you are not, you can log in with heroku login.

Set Up a Heroku App​

info

You need to do this only once per Wasp app.

Unless you want to deploy to an existing Heroku app, let's create a new Heroku app:

heroku create <app-name>

Unless you have an external Postgres database that you want to use, let's create a new database on Heroku and attach it to our app:

heroku addons:create --app <app-name> heroku-postgresql:mini
caution

Heroku does not offer a free plan anymore and mini is their cheapest database instance - it costs $5/mo.

Heroku will also set DATABASE_URL env var for us at this point. If you are using an external database, you will have to set it up yourself.

The PORT env var will also be provided by Heroku, so the only two left to set are the JWT_SECRET and WASP_WEB_CLIENT_URL env vars:

heroku config:set --app <app-name> JWT_SECRET=<random_string_at_least_32_characters_long>
heroku config:set --app <app-name> WASP_WEB_CLIENT_URL=<url_of_where_frontend_will_be_deployed>
note

If you do not know what your frontend URL is yet, don't worry. You can set WASP_WEB_CLIENT_URL after you deploy your frontend.

Deploy to a Heroku App​

After you have built the app, position yourself in .wasp/build/ directory:

cd .wasp/build

assuming you were at the root of your Wasp project at that moment.

Log in to Heroku Container Registry:

heroku container:login

Build the docker image and push it to Heroku:

heroku container:push --app <app-name> web

App is still not deployed at this point. This step might take some time, especially the very first time, since there are no cached docker layers.

Note for Apple Silicon Users

Apple Silicon users need to build a non-Arm image, so the above step will not work at this time. Instead of heroku container:push, users instead should:

docker buildx build --platform linux/amd64 -t <app-name> .
docker tag <app-name> registry.heroku.com/<app-name>/web
docker push registry.heroku.com/<app-name>/web

You are now ready to proceed to the next step.

Deploy the pushed image and restart the app:

heroku container:release --app <app-name> web

This is it, the backend is deployed at https://<app-name>-XXXX.herokuapp.com 🎉

Find out the exact app URL with:

heroku info --app <app-name>

Additionally, you can check out the logs with:

heroku logs --tail --app <app-name>
Using pg-boss with Heroku

If you wish to deploy an app leveraging Jobs that use pg-boss as the executor to Heroku, you need to set an additional environment variable called PG_BOSS_NEW_OPTIONS to {"connectionString":"<REGULAR_HEROKU_DATABASE_URL>","ssl":{"rejectUnauthorized":false}}. This is because pg-boss uses the pg extension, which does not seem to connect to Heroku over SSL by default, which Heroku requires. Additionally, Heroku uses a self-signed cert, so we must handle that as well.

Read more: https://devcenter.heroku.com/articles/connecting-heroku-postgres#connecting-in-node-js

- - + + \ No newline at end of file diff --git a/docs/0.12.0/advanced/deployment/overview.html b/docs/0.12.0/advanced/deployment/overview.html index 6046fc2fe6..f02cde5ea0 100644 --- a/docs/0.12.0/advanced/deployment/overview.html +++ b/docs/0.12.0/advanced/deployment/overview.html @@ -19,17 +19,17 @@ - - + + -
-
Version: 0.12.0

Overview

Wasp apps are full-stack apps that consist of:

  • A Node.js server.
  • A static client.
  • A PostgreSQL database.

You can deploy each part anywhere where you can usually deploy Node.js apps or static apps. For example, you can deploy your client on Netlify, the server on Fly.io, and the database on Neon.

To make deploying as smooth as possible, Wasp also offers a single-command deployment through the Wasp CLI.

Using Wasp CLI »

One command deployment & redeployment

Deploying Manually »

Build the app and deploy it manually

Click on each deployment method for more details.

Regardless of how you choose to deploy your app (i.e., manually or using the Wasp CLI), you'll need to know about some common patterns covered below.

Customizing the Dockerfile​

By default, Wasp generates a multi-stage Dockerfile. +

+
Version: 0.12.0

Overview

Wasp apps are full-stack apps that consist of:

  • A Node.js server.
  • A static client.
  • A PostgreSQL database.

You can deploy each part anywhere where you can usually deploy Node.js apps or static apps. For example, you can deploy your client on Netlify, the server on Fly.io, and the database on Neon.

To make deploying as smooth as possible, Wasp also offers a single-command deployment through the Wasp CLI.

Using Wasp CLI »

One command deployment & redeployment

Deploying Manually »

Build the app and deploy it manually

Click on each deployment method for more details.

Regardless of how you choose to deploy your app (i.e., manually or using the Wasp CLI), you'll need to know about some common patterns covered below.

Customizing the Dockerfile​

By default, Wasp generates a multi-stage Dockerfile. This file is used to build and run a Docker image with the Wasp-generated server code. It also runs any pending migrations.

You can add extra steps to this multi-stage Dockerfile by creating your own Dockerfile in the project's root directory. If Wasp finds a Dockerfile in the project's root, it appends its contents at the bottom of the default multi-stage Dockerfile.

Since the last definition in a Dockerfile wins, you can override or continue from any existing build stages. You can also choose not to use any of our build stages and have your own custom Dockerfile used as-is.

A few things to keep in mind:

  • If you override an intermediate build stage, no later build stages will be used unless you reproduce them below.
  • The generated Dockerfile's content is dynamic and depends on which features your app uses. The content can also change in future releases, so please verify it from time to time.
  • Make sure to supply ENTRYPOINT in your final build stage. Your changes won't have any effect if you don't.

Read more in the official Docker docs on multi-stage builds.

To see what your project's (potentially combined) Dockerfile will look like, run:

wasp dockerfile

Join our Discord if you have any questions, or if you need more customization than this hook provides.

- - + + \ No newline at end of file diff --git a/docs/0.12.0/advanced/email.html b/docs/0.12.0/advanced/email.html index 9c99fe0d8f..50ee517126 100644 --- a/docs/0.12.0/advanced/email.html +++ b/docs/0.12.0/advanced/email.html @@ -19,13 +19,13 @@ - - + + -
-
Version: 0.12.0

Sending Emails

With Wasp's email-sending feature, you can easily integrate email functionality into your web application.

main.wasp
app Example {
  ...
  emailSender: {
    provider: <provider>,
    defaultFrom: {
      name: "Example",
      email: "hello@itsme.com"
    },
  }
}

Choose from one of the providers:

  • Dummy (development only),
  • Mailgun,
  • SendGrid
  • or the good old SMTP.

Optionally, define the defaultFrom field, so you don't need to provide it whenever sending an email.

Sending Emails​

Before jumping into details about setting up various providers, let's see how easy it is to send emails.

You import the emailSender that is provided by the wasp/server/email module and call the send method on it.

src/actions/sendEmail.js
import { emailSender } from "wasp/server/email";

// In some action handler...
const info = await emailSender.send({
  from: {
    name: "John Doe",
    email: "john@doe.com",
  },
  to: "user@domain.com",
  subject: "Saying hello",
  text: "Hello world",
  html: "Hello <strong>world</strong>",
});

Read more about the send method in the API Reference.

The send method returns an object with the status of the sent email. It varies depending on the provider you use.

Providers​

We'll go over all of the available providers in the next section. For some of them, you'll need to set up some env variables. You can do that in the .env.server file.

Using the Dummy Provider​

Dummy Provider is not for production use

The Dummy provider is not for production use. It is only meant to be used during development. If you try building your app with the Dummy provider, the build will fail.

To speed up development, Wasp offers a Dummy email sender that console.logs the emails in the console. Since it doesn't send emails for real, it doesn't require any setup.

Set the provider to Dummy in your main.wasp file.

main.wasp
app Example {
  ...
  emailSender: {
    provider: Dummy,
  }
}

Using the SMTP Provider​

First, set the provider to SMTP in your main.wasp file.

main.wasp
app Example {
  ...
  emailSender: {
    provider: SMTP,
  }
}

Then, add the following env variables to your .env.server file.

.env.server
SMTP_HOST=
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_PORT=

Many transactional email providers (e.g. Mailgun, SendGrid but also others) can also use SMTP, so you can use them as well.

Using the Mailgun Provider​

Set the provider to Mailgun in the main.wasp file.

main.wasp
app Example {
  ...
  emailSender: {
    provider: Mailgun,
  }
}

Then, get the Mailgun API key and domain and add them to your .env.server file.

Getting the API Key and Domain​

  1. Go to Mailgun and create an account.
  2. Go to API Keys and create a new API key.
  3. Copy the API key and add it to your .env.server file.
  4. Go to Domains and create a new domain.
  5. Copy the domain and add it to your .env.server file.
.env.server
MAILGUN_API_KEY=
MAILGUN_DOMAIN=

Using the SendGrid Provider​

Set the provider field to SendGrid in your main.wasp file.

main.wasp
app Example {
  ...
  emailSender: {
    provider: SendGrid,
  }
}

Then, get the SendGrid API key and add it to your .env.server file.

Getting the API Key​

  1. Go to SendGrid and create an account.
  2. Go to API Keys and create a new API key.
  3. Copy the API key and add it to your .env.server file.
.env.server
SENDGRID_API_KEY=

API Reference​

emailSender dict​

main.wasp
app Example {
  ...
  emailSender: {
    provider: <provider>,
    defaultFrom: {
      name: "Example",
      email: "hello@itsme.com"
    },
  }
}

The emailSender dict has the following fields:

  • provider: Provider required

    The provider you want to use. Choose from Dummy, SMTP, Mailgun or SendGrid.

    Dummy Provider is not for production use

    The Dummy provider is not for production use. It is only meant to be used during development. If you try building your app with the Dummy provider, the build will fail.

  • defaultFrom: dict

    The default sender's details. If you set this field, you don't need to provide the from field when sending an email.

JavaScript API​

Using the emailSender in :

src/actions/sendEmail.js
import { emailSender } from "wasp/server/email";

// In some action handler...
const info = await emailSender.send({
  from: {
    name: "John Doe",
    email: "john@doe.com",
  },
  to: "user@domain.com",
  subject: "Saying hello",
  text: "Hello world",
  html: "Hello <strong>world</strong>",
});

The send method accepts an object with the following fields:

  • from: object

    The sender's details. If you set up defaultFrom field in the emailSender dict in Wasp file, this field is optional.

    • name: string

      The name of the sender.

    • email: string

      The email address of the sender.

  • to: string required

    The recipient's email address.

  • subject: string required

    The subject of the email.

  • text: string required

    The text version of the email.

  • html: string required

    The HTML version of the email

- - +
+
Version: 0.12.0

Sending Emails

With Wasp's email-sending feature, you can easily integrate email functionality into your web application.

main.wasp
app Example {
  ...
  emailSender: {
    provider: <provider>,
    defaultFrom: {
      name: "Example",
      email: "hello@itsme.com"
    },
  }
}

Choose from one of the providers:

  • Dummy (development only),
  • Mailgun,
  • SendGrid
  • or the good old SMTP.

Optionally, define the defaultFrom field, so you don't need to provide it whenever sending an email.

Sending Emails​

Before jumping into details about setting up various providers, let's see how easy it is to send emails.

You import the emailSender that is provided by the wasp/server/email module and call the send method on it.

src/actions/sendEmail.js
import { emailSender } from "wasp/server/email";

// In some action handler...
const info = await emailSender.send({
  from: {
    name: "John Doe",
    email: "john@doe.com",
  },
  to: "user@domain.com",
  subject: "Saying hello",
  text: "Hello world",
  html: "Hello <strong>world</strong>",
});

Read more about the send method in the API Reference.

The send method returns an object with the status of the sent email. It varies depending on the provider you use.

Providers​

We'll go over all of the available providers in the next section. For some of them, you'll need to set up some env variables. You can do that in the .env.server file.

Using the Dummy Provider​

Dummy Provider is not for production use

The Dummy provider is not for production use. It is only meant to be used during development. If you try building your app with the Dummy provider, the build will fail.

To speed up development, Wasp offers a Dummy email sender that console.logs the emails in the console. Since it doesn't send emails for real, it doesn't require any setup.

Set the provider to Dummy in your main.wasp file.

main.wasp
app Example {
  ...
  emailSender: {
    provider: Dummy,
  }
}

Using the SMTP Provider​

First, set the provider to SMTP in your main.wasp file.

main.wasp
app Example {
  ...
  emailSender: {
    provider: SMTP,
  }
}

Then, add the following env variables to your .env.server file.

.env.server
SMTP_HOST=
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_PORT=

Many transactional email providers (e.g. Mailgun, SendGrid but also others) can also use SMTP, so you can use them as well.

Using the Mailgun Provider​

Set the provider to Mailgun in the main.wasp file.

main.wasp
app Example {
  ...
  emailSender: {
    provider: Mailgun,
  }
}

Then, get the Mailgun API key and domain and add them to your .env.server file.

Getting the API Key and Domain​

  1. Go to Mailgun and create an account.
  2. Go to API Keys and create a new API key.
  3. Copy the API key and add it to your .env.server file.
  4. Go to Domains and create a new domain.
  5. Copy the domain and add it to your .env.server file.
.env.server
MAILGUN_API_KEY=
MAILGUN_DOMAIN=

Using the SendGrid Provider​

Set the provider field to SendGrid in your main.wasp file.

main.wasp
app Example {
  ...
  emailSender: {
    provider: SendGrid,
  }
}

Then, get the SendGrid API key and add it to your .env.server file.

Getting the API Key​

  1. Go to SendGrid and create an account.
  2. Go to API Keys and create a new API key.
  3. Copy the API key and add it to your .env.server file.
.env.server
SENDGRID_API_KEY=

API Reference​

emailSender dict​

main.wasp
app Example {
  ...
  emailSender: {
    provider: <provider>,
    defaultFrom: {
      name: "Example",
      email: "hello@itsme.com"
    },
  }
}

The emailSender dict has the following fields:

  • provider: Provider required

    The provider you want to use. Choose from Dummy, SMTP, Mailgun or SendGrid.

    Dummy Provider is not for production use

    The Dummy provider is not for production use. It is only meant to be used during development. If you try building your app with the Dummy provider, the build will fail.

  • defaultFrom: dict

    The default sender's details. If you set this field, you don't need to provide the from field when sending an email.

JavaScript API​

Using the emailSender in :

src/actions/sendEmail.js
import { emailSender } from "wasp/server/email";

// In some action handler...
const info = await emailSender.send({
  from: {
    name: "John Doe",
    email: "john@doe.com",
  },
  to: "user@domain.com",
  subject: "Saying hello",
  text: "Hello world",
  html: "Hello <strong>world</strong>",
});

The send method accepts an object with the following fields:

  • from: object

    The sender's details. If you set up defaultFrom field in the emailSender dict in Wasp file, this field is optional.

    • name: string

      The name of the sender.

    • email: string

      The email address of the sender.

  • to: string required

    The recipient's email address.

  • subject: string required

    The subject of the email.

  • text: string required

    The text version of the email.

  • html: string required

    The HTML version of the email

+ + \ No newline at end of file diff --git a/docs/0.12.0/advanced/jobs.html b/docs/0.12.0/advanced/jobs.html index 0f40d10bb0..9d021820af 100644 --- a/docs/0.12.0/advanced/jobs.html +++ b/docs/0.12.0/advanced/jobs.html @@ -19,13 +19,13 @@ - - + + -
-
Version: 0.12.0

Recurring Jobs

In most web apps, users send requests to the server and receive responses with some data. When the server responds quickly, the app feels responsive and smooth.

What if the server needs extra time to fully process the request? This might mean sending an email or making a slow HTTP request to an external API. In that case, it's a good idea to respond to the user as soon as possible and do the remaining work in the background.

Wasp supports background jobs that can help you with this:

  • Jobs persist between server restarts,
  • Jobs can be retried if they fail,
  • Jobs can be delayed until a future time,
  • Jobs can have a recurring schedule.

Using Jobs​

Job Definition and Usage​

Let's write an example Job that will print a message to the console and return a list of tasks from the database.

  1. Start by creating a Job declaration in your .wasp file:

    main.wasp
    job mySpecialJob {
      executor: PgBoss,
      perform: {
        fn: import { foo } from "@src/workers/bar"
      },
      entities: [Task],
    }

  2. After declaring the Job, implement its worker function:

    src/workers/bar.js
    export const foo = async ({ name }, context) => {
      console.log(`Hello ${name}!`)
      const tasks = await context.entities.Task.findMany({})
      return { tasks }
    }
    The worker function

    The worker function must be an async function. The function's return value represents the Job's result.

    The worker function accepts two arguments:

    • args: The data passed into the job when it's submitted.
    • context: { entities }: The context object containing entities you put in the Job declaration.

  3. After successfully defining the job, you can submit work to be done in your Operations or setupFn (or any other NodeJS code):

    someAction.js
    import { mySpecialJob } from 'wasp/server/jobs'

    const submittedJob = await mySpecialJob.submit({ job: "Johnny" })

    // Or, if you'd prefer it to execute in the future, just add a .delay().
    // It takes a number of seconds, Date, or ISO date string.
    await mySpecialJob
      .delay(10)
      .submit({ name: "Johnny" })

And that'is it. Your job will be executed by PgBoss as if you called foo({ name: "Johnny" }).

In our example, foo takes an argument, but passing arguments to jobs is not a requirement. It depends on how you've implemented your worker function.

Recurring Jobs​

If you have work that needs to be done on some recurring basis, you can add a schedule to your job declaration:

main.wasp
job mySpecialJob {
  executor: PgBoss,
  perform: {
    fn: import { foo } from "@src/workers/bar"
  },
  schedule: {
    cron: "0 * * * *",
    args: {=json { "job": "args" } json=} // optional
  }
}

In this example, you don't need to invoke anything in . You can imagine foo({ job: "args" }) getting automatically scheduled and invoked for you every hour.

API Reference​

Declaring Jobs​

main.wasp
job mySpecialJob {
  executor: PgBoss,
  perform: {
    fn: import { foo } from "@src/workers/bar",
    executorOptions: {
      pgBoss: {=json { "retryLimit": 1 } json=}
    }
  },
  schedule: {
    cron: "*/5 * * * *",
    args: {=json { "foo": "bar" } json=},
    executorOptions: {
      pgBoss: {=json { "retryLimit": 0 } json=}
    }
  },
  entities: [Task],
}

The Job declaration has the following fields:

  • executor: JobExecutor required

    Job executors

    Our jobs need job executors to handle the scheduling, monitoring, and execution.

    PgBoss is currently our only job executor, and is recommended for low-volume production use cases. It requires your app.db.system to be PostgreSQL.

    We have selected pg-boss as our first job executor to handle the low-volume, basic job queue workloads many web applications have. By using PostgreSQL (and SKIP LOCKED) as its storage and synchronization mechanism, it allows us to provide many job queue pros without any additional infrastructure or complex management.

    info

    Keep in mind that pg-boss jobs run alongside your other server-side code, so they are not appropriate for CPU-heavy workloads. Additionally, some care is required if you modify scheduled jobs. Please see pg-boss details below for more information.

    pg-boss details

    pg-boss provides many useful features, which can be found here.

    When you add pg-boss to a Wasp project, it will automatically add a new schema to your database called pgboss with some internal tracking tables, including job and schedule. pg-boss tables have a name column in most tables that will correspond to your Job identifier. Additionally, these tables maintain arguments, states, return values, retry information, start and expiration times, and other metadata required by pg-boss.

    If you need to customize the creation of the pg-boss instance, you can set an environment variable called PG_BOSS_NEW_OPTIONS to a stringified JSON object containing these initialization parameters. NOTE: Setting this overwrites all Wasp defaults, so you must include database connection information as well.

    pg-boss considerations​

    • Wasp starts pg-boss alongside your web server's application, where both are simultaneously operational. This means that jobs running via pg-boss and the rest of the server logic (like Operations) share the CPU, therefore you should avoid running CPU-intensive tasks via jobs.
      • Wasp does not (yet) support independent, horizontal scaling of pg-boss-only applications, nor starting them as separate workers/processes/threads.
    • The job name/identifier in your .wasp file is the same name that will be used in the name column of pg-boss tables. If you change a name that had a schedule associated with it, pg-boss will continue scheduling those jobs but they will have no handlers associated, and will thus become stale and expire. To resolve this, you can remove the applicable row from the schedule table in the pgboss schema of your database.
      • If you remove a schedule from a job, you will need to do the above as well.
    • If you wish to deploy to Heroku, you need to set an additional environment variable called PG_BOSS_NEW_OPTIONS to {"connectionString":"<REGULAR_HEROKU_DATABASE_URL>","ssl":{"rejectUnauthorized":false}}. This is because pg-boss uses the pg extension, which does not seem to connect to Heroku over SSL by default, which Heroku requires. Additionally, Heroku uses a self-signed cert, so we must handle that as well.
    • https://devcenter.heroku.com/articles/connecting-heroku-postgres#connecting-in-node-js

  • perform: dict required

    • fn: ExtImport required

      • An async function that performs the work. Since Wasp executes Jobs on the server, the import path must lead to a NodeJS file.
      • It receives the following arguments:
        • args: Input: The data passed to the job when it's submitted.
        • context: { entities: Entities }: The context object containing any declared entities.

      Here's an example of a perform.fn function:

      src/workers/bar.js
      export const foo = async ({ name }, context) => {
        console.log(`Hello ${name}!`)
        const tasks = await context.entities.Task.findMany({})
        return { tasks }
      }

    • executorOptions: dict

      Executor-specific default options to use when submitting jobs. These are passed directly through and you should consult the documentation for the job executor. These can be overridden during invocation with submit() or in a schedule.

      • pgBoss: JSON

        See the docs for pg-boss.

  • schedule: dict

    • cron: string required

      A 5-placeholder format cron expression string. See rationale for minute-level precision here.

      If you need help building cron expressions, Check out Crontab guru.

    • args: JSON

      The arguments to pass to the perform.fn function when invoked.

    • executorOptions: dict

      Executor-specific options to use when submitting jobs. These are passed directly through and you should consult the documentation for the job executor. The perform.executorOptions are the default options, and schedule.executorOptions can override/extend those.

      • pgBoss: JSON

        See the docs for pg-boss.

  • entities: [Entity]

    A list of entities you wish to use inside your Job (similar to Queries and Actions).

JavaScript API​

  • Importing a Job:

    someAction.js
    import { mySpecialJob } from 'wasp/server/jobs'

  • submit(jobArgs, executorOptions)

    • jobArgs: Input

    • executorOptions: object

      Submits a Job to be executed by an executor, optionally passing in a JSON job argument your job handler function receives, and executor-specific submit options.

    someAction.js
    const submittedJob = await mySpecialJob.submit({ job: "args" })

  • delay(startAfter)

    • startAfter: int | string | Date required

      Delaying the invocation of the job handler. The delay can be one of:

      • Integer: number of seconds to delay. [Default 0]
      • String: ISO date string to run at.
      • Date: Date to run at.
    someAction.js
    const submittedJob = await mySpecialJob
      .delay(10)
      .submit({ job: "args" }, { "retryLimit": 2 })

Tracking​

The return value of submit() is an instance of SubmittedJob, which has the following fields:

  • jobId: The ID for the job in that executor.
  • jobName: The name of the job you used in your .wasp file.
  • executorName: The Symbol of the name of the job executor.

There are also some namespaced, job executor-specific objects.

  • For pg-boss, you may access: pgBoss
    • details(): pg-boss specific job detail information. Reference
    • cancel(): attempts to cancel a job. Reference
    • resume(): attempts to resume a canceled job. Reference
- - +
+
Version: 0.12.0

Recurring Jobs

In most web apps, users send requests to the server and receive responses with some data. When the server responds quickly, the app feels responsive and smooth.

What if the server needs extra time to fully process the request? This might mean sending an email or making a slow HTTP request to an external API. In that case, it's a good idea to respond to the user as soon as possible and do the remaining work in the background.

Wasp supports background jobs that can help you with this:

  • Jobs persist between server restarts,
  • Jobs can be retried if they fail,
  • Jobs can be delayed until a future time,
  • Jobs can have a recurring schedule.

Using Jobs​

Job Definition and Usage​

Let's write an example Job that will print a message to the console and return a list of tasks from the database.

  1. Start by creating a Job declaration in your .wasp file:

    main.wasp
    job mySpecialJob {
      executor: PgBoss,
      perform: {
        fn: import { foo } from "@src/workers/bar"
      },
      entities: [Task],
    }

  2. After declaring the Job, implement its worker function:

    src/workers/bar.js
    export const foo = async ({ name }, context) => {
      console.log(`Hello ${name}!`)
      const tasks = await context.entities.Task.findMany({})
      return { tasks }
    }
    The worker function

    The worker function must be an async function. The function's return value represents the Job's result.

    The worker function accepts two arguments:

    • args: The data passed into the job when it's submitted.
    • context: { entities }: The context object containing entities you put in the Job declaration.

  3. After successfully defining the job, you can submit work to be done in your Operations or setupFn (or any other NodeJS code):

    someAction.js
    import { mySpecialJob } from 'wasp/server/jobs'

    const submittedJob = await mySpecialJob.submit({ job: "Johnny" })

    // Or, if you'd prefer it to execute in the future, just add a .delay().
    // It takes a number of seconds, Date, or ISO date string.
    await mySpecialJob
      .delay(10)
      .submit({ name: "Johnny" })

And that'is it. Your job will be executed by PgBoss as if you called foo({ name: "Johnny" }).

In our example, foo takes an argument, but passing arguments to jobs is not a requirement. It depends on how you've implemented your worker function.

Recurring Jobs​

If you have work that needs to be done on some recurring basis, you can add a schedule to your job declaration:

main.wasp
job mySpecialJob {
  executor: PgBoss,
  perform: {
    fn: import { foo } from "@src/workers/bar"
  },
  schedule: {
    cron: "0 * * * *",
    args: {=json { "job": "args" } json=} // optional
  }
}

In this example, you don't need to invoke anything in . You can imagine foo({ job: "args" }) getting automatically scheduled and invoked for you every hour.

API Reference​

Declaring Jobs​

main.wasp
job mySpecialJob {
  executor: PgBoss,
  perform: {
    fn: import { foo } from "@src/workers/bar",
    executorOptions: {
      pgBoss: {=json { "retryLimit": 1 } json=}
    }
  },
  schedule: {
    cron: "*/5 * * * *",
    args: {=json { "foo": "bar" } json=},
    executorOptions: {
      pgBoss: {=json { "retryLimit": 0 } json=}
    }
  },
  entities: [Task],
}

The Job declaration has the following fields:

  • executor: JobExecutor required

    Job executors

    Our jobs need job executors to handle the scheduling, monitoring, and execution.

    PgBoss is currently our only job executor, and is recommended for low-volume production use cases. It requires your app.db.system to be PostgreSQL.

    We have selected pg-boss as our first job executor to handle the low-volume, basic job queue workloads many web applications have. By using PostgreSQL (and SKIP LOCKED) as its storage and synchronization mechanism, it allows us to provide many job queue pros without any additional infrastructure or complex management.

    info

    Keep in mind that pg-boss jobs run alongside your other server-side code, so they are not appropriate for CPU-heavy workloads. Additionally, some care is required if you modify scheduled jobs. Please see pg-boss details below for more information.

    pg-boss details

    pg-boss provides many useful features, which can be found here.

    When you add pg-boss to a Wasp project, it will automatically add a new schema to your database called pgboss with some internal tracking tables, including job and schedule. pg-boss tables have a name column in most tables that will correspond to your Job identifier. Additionally, these tables maintain arguments, states, return values, retry information, start and expiration times, and other metadata required by pg-boss.

    If you need to customize the creation of the pg-boss instance, you can set an environment variable called PG_BOSS_NEW_OPTIONS to a stringified JSON object containing these initialization parameters. NOTE: Setting this overwrites all Wasp defaults, so you must include database connection information as well.

    pg-boss considerations​

    • Wasp starts pg-boss alongside your web server's application, where both are simultaneously operational. This means that jobs running via pg-boss and the rest of the server logic (like Operations) share the CPU, therefore you should avoid running CPU-intensive tasks via jobs.
      • Wasp does not (yet) support independent, horizontal scaling of pg-boss-only applications, nor starting them as separate workers/processes/threads.
    • The job name/identifier in your .wasp file is the same name that will be used in the name column of pg-boss tables. If you change a name that had a schedule associated with it, pg-boss will continue scheduling those jobs but they will have no handlers associated, and will thus become stale and expire. To resolve this, you can remove the applicable row from the schedule table in the pgboss schema of your database.
      • If you remove a schedule from a job, you will need to do the above as well.
    • If you wish to deploy to Heroku, you need to set an additional environment variable called PG_BOSS_NEW_OPTIONS to {"connectionString":"<REGULAR_HEROKU_DATABASE_URL>","ssl":{"rejectUnauthorized":false}}. This is because pg-boss uses the pg extension, which does not seem to connect to Heroku over SSL by default, which Heroku requires. Additionally, Heroku uses a self-signed cert, so we must handle that as well.
    • https://devcenter.heroku.com/articles/connecting-heroku-postgres#connecting-in-node-js

  • perform: dict required

    • fn: ExtImport required

      • An async function that performs the work. Since Wasp executes Jobs on the server, the import path must lead to a NodeJS file.
      • It receives the following arguments:
        • args: Input: The data passed to the job when it's submitted.
        • context: { entities: Entities }: The context object containing any declared entities.

      Here's an example of a perform.fn function:

      src/workers/bar.js
      export const foo = async ({ name }, context) => {
        console.log(`Hello ${name}!`)
        const tasks = await context.entities.Task.findMany({})
        return { tasks }
      }

    • executorOptions: dict

      Executor-specific default options to use when submitting jobs. These are passed directly through and you should consult the documentation for the job executor. These can be overridden during invocation with submit() or in a schedule.

      • pgBoss: JSON

        See the docs for pg-boss.

  • schedule: dict

    • cron: string required

      A 5-placeholder format cron expression string. See rationale for minute-level precision here.

      If you need help building cron expressions, Check out Crontab guru.

    • args: JSON

      The arguments to pass to the perform.fn function when invoked.

    • executorOptions: dict

      Executor-specific options to use when submitting jobs. These are passed directly through and you should consult the documentation for the job executor. The perform.executorOptions are the default options, and schedule.executorOptions can override/extend those.

      • pgBoss: JSON

        See the docs for pg-boss.

  • entities: [Entity]

    A list of entities you wish to use inside your Job (similar to Queries and Actions).

JavaScript API​

  • Importing a Job:

    someAction.js
    import { mySpecialJob } from 'wasp/server/jobs'

  • submit(jobArgs, executorOptions)

    • jobArgs: Input

    • executorOptions: object

      Submits a Job to be executed by an executor, optionally passing in a JSON job argument your job handler function receives, and executor-specific submit options.

    someAction.js
    const submittedJob = await mySpecialJob.submit({ job: "args" })

  • delay(startAfter)

    • startAfter: int | string | Date required

      Delaying the invocation of the job handler. The delay can be one of:

      • Integer: number of seconds to delay. [Default 0]
      • String: ISO date string to run at.
      • Date: Date to run at.
    someAction.js
    const submittedJob = await mySpecialJob
      .delay(10)
      .submit({ job: "args" }, { "retryLimit": 2 })

Tracking​

The return value of submit() is an instance of SubmittedJob, which has the following fields:

  • jobId: The ID for the job in that executor.
  • jobName: The name of the job you used in your .wasp file.
  • executorName: The Symbol of the name of the job executor.

There are also some namespaced, job executor-specific objects.

  • For pg-boss, you may access: pgBoss
    • details(): pg-boss specific job detail information. Reference
    • cancel(): attempts to cancel a job. Reference
    • resume(): attempts to resume a canceled job. Reference
+ + \ No newline at end of file diff --git a/docs/0.12.0/advanced/links.html b/docs/0.12.0/advanced/links.html index b79057b9cd..20c3f98571 100644 --- a/docs/0.12.0/advanced/links.html +++ b/docs/0.12.0/advanced/links.html @@ -19,13 +19,13 @@ - - + + -
-
Version: 0.12.0

Type-Safe Links

If you are using Typescript, you can use Wasp's custom Link component to create type-safe links to other pages on your site.

After you defined a route:

main.wasp
route TaskRoute { path: "/task/:id", to: TaskPage }
page TaskPage { ... }

You can get the benefits of type-safe links by using the Link component from wasp/client/router:

TaskList.tsx
import { Link } from 'wasp/client/router'

export const TaskList = () => {
  // ...

  return (
    <div>
      {tasks.map((task) => (
        <Link
          key={task.id}
          to="/task/:id"
          {/* 👆 You must provide a valid path here */}
          params={{ id: task.id }}>
          {/* 👆 All the params must be correctly passed in */}
          {task.description}
        </Link>
      ))}
    </div>
  )
}

Using Search Query & Hash​

You can also pass search and hash props to the Link component:

TaskList.tsx
<Link
  to="/task/:id"
  params={{ id: task.id }}
  search={{ sortBy: 'date' }}
  hash="comments"
>
  {task.description}
</Link>

This will result in a link like this: /task/1?sortBy=date#comments. Check out the API Reference for more details.

The routes Object​

You can also get all the pages in your app with the routes object:

TaskList.tsx
import { routes } from 'wasp/client/router'

const linkToTask = routes.TaskRoute.build({ params: { id: 1 } })

This will result in a link like this: /task/1.

You can also pass search and hash props to the build function. Check out the API Reference for more details.

API Reference​

The Link component accepts the following props:

  • to required

    • A valid Wasp Route path from your main.wasp file.

  • params: { [name: string]: string | number } required (if the path contains params)

    • An object with keys and values for each param in the path.
    • For example, if the path is /task/:id, then the params prop must be { id: 1 }. Wasp supports required and optional params.

  • search: string[][] | Record<string, string> | string | URLSearchParams

    • Any valid input for URLSearchParams constructor.
    • For example, the object { sortBy: 'date' } becomes ?sortBy=date.

  • hash: string

  • all other props that the react-router-dom's Link component accepts

routes Object​

The routes object contains a function for each route in your app.

router.tsx
export const routes = {
  // RootRoute has a path like "/"
  RootRoute: {
    build: (options?: {
      search?: string[][] | Record<string, string> | string | URLSearchParams
      hash?: string
    }) => // ...
  },

  // DetailRoute has a path like "/task/:id/:something?"
  DetailRoute: {
    build: (
      options: {
        params: { id: ParamValue; something?: ParamValue; },
        search?: string[][] | Record<string, string> | string | URLSearchParams
        hash?: string
      }
    ) => // ...
  }
}

The params object is required if the route contains params. The search and hash parameters are optional.

You can use the routes object like this:

import { routes } from 'wasp/client/router'

const linkToRoot = routes.RootRoute.build()
const linkToTask = routes.DetailRoute.build({ params: { id: 1 } })
- - +
+
Version: 0.12.0

Type-Safe Links

If you are using Typescript, you can use Wasp's custom Link component to create type-safe links to other pages on your site.

After you defined a route:

main.wasp
route TaskRoute { path: "/task/:id", to: TaskPage }
page TaskPage { ... }

You can get the benefits of type-safe links by using the Link component from wasp/client/router:

TaskList.tsx
import { Link } from 'wasp/client/router'

export const TaskList = () => {
  // ...

  return (
    <div>
      {tasks.map((task) => (
        <Link
          key={task.id}
          to="/task/:id"
          {/* 👆 You must provide a valid path here */}
          params={{ id: task.id }}>
          {/* 👆 All the params must be correctly passed in */}
          {task.description}
        </Link>
      ))}
    </div>
  )
}

Using Search Query & Hash​

You can also pass search and hash props to the Link component:

TaskList.tsx
<Link
  to="/task/:id"
  params={{ id: task.id }}
  search={{ sortBy: 'date' }}
  hash="comments"
>
  {task.description}
</Link>

This will result in a link like this: /task/1?sortBy=date#comments. Check out the API Reference for more details.

The routes Object​

You can also get all the pages in your app with the routes object:

TaskList.tsx
import { routes } from 'wasp/client/router'

const linkToTask = routes.TaskRoute.build({ params: { id: 1 } })

This will result in a link like this: /task/1.

You can also pass search and hash props to the build function. Check out the API Reference for more details.

API Reference​

The Link component accepts the following props:

  • to required

    • A valid Wasp Route path from your main.wasp file.

  • params: { [name: string]: string | number } required (if the path contains params)

    • An object with keys and values for each param in the path.
    • For example, if the path is /task/:id, then the params prop must be { id: 1 }. Wasp supports required and optional params.

  • search: string[][] | Record<string, string> | string | URLSearchParams

    • Any valid input for URLSearchParams constructor.
    • For example, the object { sortBy: 'date' } becomes ?sortBy=date.

  • hash: string

  • all other props that the react-router-dom's Link component accepts

routes Object​

The routes object contains a function for each route in your app.

router.tsx
export const routes = {
  // RootRoute has a path like "/"
  RootRoute: {
    build: (options?: {
      search?: string[][] | Record<string, string> | string | URLSearchParams
      hash?: string
    }) => // ...
  },

  // DetailRoute has a path like "/task/:id/:something?"
  DetailRoute: {
    build: (
      options: {
        params: { id: ParamValue; something?: ParamValue; },
        search?: string[][] | Record<string, string> | string | URLSearchParams
        hash?: string
      }
    ) => // ...
  }
}

The params object is required if the route contains params. The search and hash parameters are optional.

You can use the routes object like this:

import { routes } from 'wasp/client/router'

const linkToRoot = routes.RootRoute.build()
const linkToTask = routes.DetailRoute.build({ params: { id: 1 } })
+ + \ No newline at end of file diff --git a/docs/0.12.0/advanced/middleware-config.html b/docs/0.12.0/advanced/middleware-config.html index bd0d8c5b6f..744ebad3cc 100644 --- a/docs/0.12.0/advanced/middleware-config.html +++ b/docs/0.12.0/advanced/middleware-config.html @@ -19,13 +19,13 @@ - - + + -
-
Version: 0.12.0

Configuring Middleware

Wasp comes with a minimal set of useful Express middleware in every application. While this is good for most users, we realize some may wish to add, modify, or remove some of these choices both globally, or on a per-api/path basis.

Default Global Middleware 🌍​

Wasp's Express server has the following middleware by default:

  • Helmet: Helmet helps you secure your Express apps by setting various HTTP headers. It's not a silver bullet, but it's a good start.

  • CORS: CORS is a package for providing a middleware that can be used to enable CORS with various options.

    note

    CORS middleware is required for the frontend to communicate with the backend.

  • Morgan: HTTP request logger middleware.

  • express.json (which uses body-parser): parses incoming request bodies in a middleware before your handlers, making the result available under the req.body property.

    note

    JSON middlware is required for Operations to function properly.

  • express.urlencoded (which uses body-parser): returns middleware that only parses urlencoded bodies and only looks at requests where the Content-Type header matches the type option.

  • cookieParser: parses Cookie header and populates req.cookies with an object keyed by the cookie names.

Customization​

You have three places where you can customize middleware:

  1. global: here, any changes will apply by default to all operations (query and action) and api. This is helpful if you wanted to add support for multiple domains to CORS, for example.

    Modifying global middleware

    Please treat modifications to global middleware with extreme care as they will affect all operations and APIs. If you are unsure, use one of the other two options.

  2. per-api: you can override middleware for a specific api route (e.g. POST /webhook/callback). This is helpful if you want to disable JSON parsing for some callback, for example.

  3. per-path: this is helpful if you need to customize middleware for all methods under a given path.

    • It's helpful for things like "complex CORS requests" which may need to apply to both OPTIONS and GET, or to apply some middleware to a set of api routes.

Default Middleware Definitions​

Below is the actual definitions of default middleware which you can override.

const defaultGlobalMiddleware = new Map([
  ['helmet', helmet()],
  ['cors', cors({ origin: config.allowedCORSOrigins })],
  ['logger', logger('dev')],
  ['express.json', express.json()],
  ['express.urlencoded', express.urlencoded({ extended: false })],
  ['cookieParser', cookieParser()]
])

1. Customize Global Middleware​

If you would like to modify the middleware for all operations and APIs, you can do something like:

main.wasp
app todoApp {
  // ...

  server: {
    setupFn: import setup from "@src/serverSetup",
    middlewareConfigFn: import { serverMiddlewareFn } from "@src/serverSetup"
  },
}
src/serverSetup.js
import cors from 'cors'
import { config } from 'wasp/server'

export const serverMiddlewareFn = (middlewareConfig) => {
  // Example of adding extra domains to CORS.
  middlewareConfig.set('cors', cors({ origin: [config.frontendUrl, 'https://example1.com', 'https://example2.com'] }))
  return middlewareConfig
}

2. Customize api-specific Middleware​

If you would like to modify the middleware for a single API, you can do something like:

main.wasp
// ...

api webhookCallback {
  fn: import { webhookCallback } from "@src/apis",
  middlewareConfigFn: import { webhookCallbackMiddlewareFn } from "@src/apis",
  httpRoute: (POST, "/webhook/callback"),
  auth: false
}
src/apis.js
import express from 'express'

export const webhookCallback = (req, res, _context) => {
  res.json({ msg: req.body.length })
}

export const webhookCallbackMiddlewareFn = (middlewareConfig) => {
  console.log('webhookCallbackMiddlewareFn: Swap express.json for express.raw')

  middlewareConfig.delete('express.json')
  middlewareConfig.set('express.raw', express.raw({ type: '*/*' }))

  return middlewareConfig
}

note

This gets installed on a per-method basis. Behind the scenes, this results in code like:

router.post('/webhook/callback', webhookCallbackMiddleware, ...)

3. Customize Per-Path Middleware​

If you would like to modify the middleware for all API routes under some common path, you can define a middlewareConfigFn on an apiNamespace:

main.wasp
// ...

apiNamespace fooBar {
  middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@src/apis",
  path: "/foo/bar"
}
src/apis.js
export const fooBarNamespaceMiddlewareFn = (middlewareConfig) => {
  const customMiddleware = (_req, _res, next) => {
    console.log('fooBarNamespaceMiddlewareFn: custom middleware')
    next()
  }

  middlewareConfig.set('custom.middleware', customMiddleware)

  return middlewareConfig
}
note

This gets installed at the router level for the path. Behind the scenes, this results in something like:

router.use('/foo/bar', fooBarNamespaceMiddleware)
- - +
+
Version: 0.12.0

Configuring Middleware

Wasp comes with a minimal set of useful Express middleware in every application. While this is good for most users, we realize some may wish to add, modify, or remove some of these choices both globally, or on a per-api/path basis.

Default Global Middleware 🌍​

Wasp's Express server has the following middleware by default:

  • Helmet: Helmet helps you secure your Express apps by setting various HTTP headers. It's not a silver bullet, but it's a good start.

  • CORS: CORS is a package for providing a middleware that can be used to enable CORS with various options.

    note

    CORS middleware is required for the frontend to communicate with the backend.

  • Morgan: HTTP request logger middleware.

  • express.json (which uses body-parser): parses incoming request bodies in a middleware before your handlers, making the result available under the req.body property.

    note

    JSON middlware is required for Operations to function properly.

  • express.urlencoded (which uses body-parser): returns middleware that only parses urlencoded bodies and only looks at requests where the Content-Type header matches the type option.

  • cookieParser: parses Cookie header and populates req.cookies with an object keyed by the cookie names.

Customization​

You have three places where you can customize middleware:

  1. global: here, any changes will apply by default to all operations (query and action) and api. This is helpful if you wanted to add support for multiple domains to CORS, for example.

    Modifying global middleware

    Please treat modifications to global middleware with extreme care as they will affect all operations and APIs. If you are unsure, use one of the other two options.

  2. per-api: you can override middleware for a specific api route (e.g. POST /webhook/callback). This is helpful if you want to disable JSON parsing for some callback, for example.

  3. per-path: this is helpful if you need to customize middleware for all methods under a given path.

    • It's helpful for things like "complex CORS requests" which may need to apply to both OPTIONS and GET, or to apply some middleware to a set of api routes.

Default Middleware Definitions​

Below is the actual definitions of default middleware which you can override.

const defaultGlobalMiddleware = new Map([
  ['helmet', helmet()],
  ['cors', cors({ origin: config.allowedCORSOrigins })],
  ['logger', logger('dev')],
  ['express.json', express.json()],
  ['express.urlencoded', express.urlencoded({ extended: false })],
  ['cookieParser', cookieParser()]
])

1. Customize Global Middleware​

If you would like to modify the middleware for all operations and APIs, you can do something like:

main.wasp
app todoApp {
  // ...

  server: {
    setupFn: import setup from "@src/serverSetup",
    middlewareConfigFn: import { serverMiddlewareFn } from "@src/serverSetup"
  },
}
src/serverSetup.js
import cors from 'cors'
import { config } from 'wasp/server'

export const serverMiddlewareFn = (middlewareConfig) => {
  // Example of adding extra domains to CORS.
  middlewareConfig.set('cors', cors({ origin: [config.frontendUrl, 'https://example1.com', 'https://example2.com'] }))
  return middlewareConfig
}

2. Customize api-specific Middleware​

If you would like to modify the middleware for a single API, you can do something like:

main.wasp
// ...

api webhookCallback {
  fn: import { webhookCallback } from "@src/apis",
  middlewareConfigFn: import { webhookCallbackMiddlewareFn } from "@src/apis",
  httpRoute: (POST, "/webhook/callback"),
  auth: false
}
src/apis.js
import express from 'express'

export const webhookCallback = (req, res, _context) => {
  res.json({ msg: req.body.length })
}

export const webhookCallbackMiddlewareFn = (middlewareConfig) => {
  console.log('webhookCallbackMiddlewareFn: Swap express.json for express.raw')

  middlewareConfig.delete('express.json')
  middlewareConfig.set('express.raw', express.raw({ type: '*/*' }))

  return middlewareConfig
}

note

This gets installed on a per-method basis. Behind the scenes, this results in code like:

router.post('/webhook/callback', webhookCallbackMiddleware, ...)

3. Customize Per-Path Middleware​

If you would like to modify the middleware for all API routes under some common path, you can define a middlewareConfigFn on an apiNamespace:

main.wasp
// ...

apiNamespace fooBar {
  middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@src/apis",
  path: "/foo/bar"
}
src/apis.js
export const fooBarNamespaceMiddlewareFn = (middlewareConfig) => {
  const customMiddleware = (_req, _res, next) => {
    console.log('fooBarNamespaceMiddlewareFn: custom middleware')
    next()
  }

  middlewareConfig.set('custom.middleware', customMiddleware)

  return middlewareConfig
}
note

This gets installed at the router level for the path. Behind the scenes, this results in something like:

router.use('/foo/bar', fooBarNamespaceMiddleware)
+ + \ No newline at end of file diff --git a/docs/0.12.0/advanced/web-sockets.html b/docs/0.12.0/advanced/web-sockets.html index c38c81f35a..3f16c1b12a 100644 --- a/docs/0.12.0/advanced/web-sockets.html +++ b/docs/0.12.0/advanced/web-sockets.html @@ -19,13 +19,13 @@ - - + + -
-
Version: 0.12.0

Web Sockets

Wasp provides a fully integrated WebSocket experience by utilizing Socket.IO on the client and server.

We handle making sure your URLs are correctly setup, CORS is enabled, and provide a useful useSocket and useSocketListener abstractions for use in React components.

To get started, you need to:

  1. Define your WebSocket logic on the server.
  2. Enable WebSockets in your Wasp file, and connect it with your server logic.
  3. Use WebSockets on the client, in React, via useSocket and useSocketListener.
  4. Optionally, type the WebSocket events and payloads for full-stack type safety.

Let's go through setting up WebSockets step by step, starting with enabling WebSockets in your Wasp file.

Turn On WebSockets in Your Wasp File​

We specify that we are using WebSockets by adding webSocket to our app and providing the required fn. You can optionally change the auto-connect behavior.

todoApp.wasp
app todoApp {
  // ...

  webSocket: {
    fn: import { webSocketFn } from "@src/webSocket",
    autoConnect: true, // optional, default: true
  },
}

Defining the Events Handler​

Let's define the WebSockets server with all of the events and handler functions.

webSocketFn Function​

On the server, you will get Socket.IO io: Server argument and context for your WebSocket function. The context object give you access to all of the entities from your Wasp app.

You can use this io object to register callbacks for all the regular Socket.IO events. Also, if a user is logged in, you will have a socket.data.user on the server.

This is how we can define our webSocketFn function:

src/webSocket.js
import { v4 as uuidv4 } from 'uuid'
import { getFirstProviderUserId } from 'wasp/auth'

export const webSocketFn = (io, context) => {
  io.on('connection', (socket) => {
    const username = getFirstProviderUserId(socket.data.user) ?? 'Unknown'
    console.log('a user connected: ', username)

    socket.on('chatMessage', async (msg) => {
      console.log('message: ', msg)
      io.emit('chatMessage', { id: uuidv4(), username, text: msg })
      // You can also use your entities here:
      // await context.entities.SomeEntity.create({ someField: msg })
    })
  })
}

Using the WebSocket On The Client​

useSocket Hook​

Client access to WebSockets is provided by the useSocket hook. It returns:

  • socket: Socket for sending and receiving events.
  • isConnected: boolean for showing a display of the Socket.IO connection status.
    • Note: Wasp automatically connects and establishes a WebSocket connection from the client to the server by default, so you do not need to explicitly socket.connect() or socket.disconnect().
    • If you set autoConnect: false in your Wasp file, then you should call these as needed.

All components using useSocket share the same underlying socket.

useSocketListener Hook​

Additionally, there is a useSocketListener: (event, callback) => void hook which is used for registering event handlers. It takes care of unregistering the handler on unmount.

src/ChatPage.jsx
import React, { useState } from 'react'
import {
  useSocket,
  useSocketListener,
} from 'wasp/client/webSocket'

export const ChatPage = () => {
  const [messageText, setMessageText] = useState('')
  const [messages, setMessages] = useState([])
  const { socket, isConnected } = useSocket()

  useSocketListener('chatMessage', logMessage)

  function logMessage(msg) {
    setMessages((priorMessages) => [msg, ...priorMessages])
  }

  function handleSubmit(e) {
    e.preventDefault()
    socket.emit('chatMessage', messageText)
    setMessageText('')
  }

  const messageList = messages.map((msg) => (
    <li key={msg.id}>
      <em>{msg.username}</em>: {msg.text}
    </li>
  ))
  const connectionIcon = isConnected ? '🟢' : '🔴'

  return (
    <>
      <h2>Chat {connectionIcon}</h2>
      <div>
        <form onSubmit={handleSubmit}>
          <div>
            <div>
              <input
                type="text"
                value={messageText}
                onChange={(e) => setMessageText(e.target.value)}
              />
            </div>
            <div>
              <button type="submit">Submit</button>
            </div>
          </div>
        </form>
        <ul>{messageList}</ul>
      </div>
    </>
  )
}

API Reference​

todoApp.wasp
app todoApp {
  // ...

  webSocket: {
    fn: import { webSocketFn } from "@src/webSocket",
    autoConnect: true, // optional, default: true
  },
}

The webSocket dict has the following fields:

  • fn: WebSocketFn required

    The function that defines the WebSocket events and handlers.

  • autoConnect: bool

    Whether to automatically connect to the WebSocket server. Default: true.

- - +
+
Version: 0.12.0

Web Sockets

Wasp provides a fully integrated WebSocket experience by utilizing Socket.IO on the client and server.

We handle making sure your URLs are correctly setup, CORS is enabled, and provide a useful useSocket and useSocketListener abstractions for use in React components.

To get started, you need to:

  1. Define your WebSocket logic on the server.
  2. Enable WebSockets in your Wasp file, and connect it with your server logic.
  3. Use WebSockets on the client, in React, via useSocket and useSocketListener.
  4. Optionally, type the WebSocket events and payloads for full-stack type safety.

Let's go through setting up WebSockets step by step, starting with enabling WebSockets in your Wasp file.

Turn On WebSockets in Your Wasp File​

We specify that we are using WebSockets by adding webSocket to our app and providing the required fn. You can optionally change the auto-connect behavior.

todoApp.wasp
app todoApp {
  // ...

  webSocket: {
    fn: import { webSocketFn } from "@src/webSocket",
    autoConnect: true, // optional, default: true
  },
}

Defining the Events Handler​

Let's define the WebSockets server with all of the events and handler functions.

webSocketFn Function​

On the server, you will get Socket.IO io: Server argument and context for your WebSocket function. The context object give you access to all of the entities from your Wasp app.

You can use this io object to register callbacks for all the regular Socket.IO events. Also, if a user is logged in, you will have a socket.data.user on the server.

This is how we can define our webSocketFn function:

src/webSocket.js
import { v4 as uuidv4 } from 'uuid'
import { getFirstProviderUserId } from 'wasp/auth'

export const webSocketFn = (io, context) => {
  io.on('connection', (socket) => {
    const username = getFirstProviderUserId(socket.data.user) ?? 'Unknown'
    console.log('a user connected: ', username)

    socket.on('chatMessage', async (msg) => {
      console.log('message: ', msg)
      io.emit('chatMessage', { id: uuidv4(), username, text: msg })
      // You can also use your entities here:
      // await context.entities.SomeEntity.create({ someField: msg })
    })
  })
}

Using the WebSocket On The Client​

useSocket Hook​

Client access to WebSockets is provided by the useSocket hook. It returns:

  • socket: Socket for sending and receiving events.
  • isConnected: boolean for showing a display of the Socket.IO connection status.
    • Note: Wasp automatically connects and establishes a WebSocket connection from the client to the server by default, so you do not need to explicitly socket.connect() or socket.disconnect().
    • If you set autoConnect: false in your Wasp file, then you should call these as needed.

All components using useSocket share the same underlying socket.

useSocketListener Hook​

Additionally, there is a useSocketListener: (event, callback) => void hook which is used for registering event handlers. It takes care of unregistering the handler on unmount.

src/ChatPage.jsx
import React, { useState } from 'react'
import {
  useSocket,
  useSocketListener,
} from 'wasp/client/webSocket'

export const ChatPage = () => {
  const [messageText, setMessageText] = useState('')
  const [messages, setMessages] = useState([])
  const { socket, isConnected } = useSocket()

  useSocketListener('chatMessage', logMessage)

  function logMessage(msg) {
    setMessages((priorMessages) => [msg, ...priorMessages])
  }

  function handleSubmit(e) {
    e.preventDefault()
    socket.emit('chatMessage', messageText)
    setMessageText('')
  }

  const messageList = messages.map((msg) => (
    <li key={msg.id}>
      <em>{msg.username}</em>: {msg.text}
    </li>
  ))
  const connectionIcon = isConnected ? '🟢' : '🔴'

  return (
    <>
      <h2>Chat {connectionIcon}</h2>
      <div>
        <form onSubmit={handleSubmit}>
          <div>
            <div>
              <input
                type="text"
                value={messageText}
                onChange={(e) => setMessageText(e.target.value)}
              />
            </div>
            <div>
              <button type="submit">Submit</button>
            </div>
          </div>
        </form>
        <ul>{messageList}</ul>
      </div>
    </>
  )
}

API Reference​

todoApp.wasp
app todoApp {
  // ...

  webSocket: {
    fn: import { webSocketFn } from "@src/webSocket",
    autoConnect: true, // optional, default: true
  },
}

The webSocket dict has the following fields:

  • fn: WebSocketFn required

    The function that defines the WebSocket events and handlers.

  • autoConnect: bool

    Whether to automatically connect to the WebSocket server. Default: true.

+ + \ No newline at end of file diff --git a/docs/0.12.0/auth/email.html b/docs/0.12.0/auth/email.html index 045b356569..f97ae18cd1 100644 --- a/docs/0.12.0/auth/email.html +++ b/docs/0.12.0/auth/email.html @@ -19,13 +19,13 @@ - - + + -
-
Version: 0.12.0

Email

Wasp supports e-mail authentication out of the box, along with email verification and "forgot your password?" flows. It provides you with the server-side implementation and email templates for all of these flows.

Auth UI

Using multiple auth identities for a single user

Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

Setting Up Email Authentication​

We'll need to take the following steps to set up email authentication:

  1. Enable email authentication in the Wasp file
  2. Add the User entity
  3. Add the auth routes and pages
  4. Use Auth UI components in our pages
  5. Set up the email sender

Structure of the main.wasp file we will end up with:

main.wasp
// Configuring e-mail authentication
app myApp {
  auth: { ... }
}

// Defining User entity
entity User { ... }

// Defining routes and pages
route SignupRoute { ... }
page SignupPage { ... }
// ...

1. Enable Email Authentication in main.wasp​

Let's start with adding the following to our main.wasp file:

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    // 1. Specify the user entity (we'll define it next)
    userEntity: User,
    methods: {
      // 2. Enable email authentication
      email: {
        // 3. Specify the email from field
        fromField: {
          name: "My App Postman",
          email: "hello@itsme.com"
        },
        // 4. Specify the email verification and password reset options (we'll talk about them later)
        emailVerification: {
          clientRoute: EmailVerificationRoute,
        },
        passwordReset: {
          clientRoute: PasswordResetRoute,
        },
      },
    },
    onAuthFailedRedirectTo: "/login",
    onAuthSucceededRedirectTo: "/"
  },
}

Read more about the email auth method options here.

2. Add the User Entity​

The User entity can be as simple as including only the id field:

main.wasp
// 5. Define the user entity
entity User {=psl
    id                        Int           @id @default(autoincrement())
    // Add your own fields below
    // ...
psl=}

You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

3. Add the Routes and Pages​

Next, we need to define the routes and pages for the authentication pages.

Add the following to the main.wasp file:

main.wasp
// ...

// 6. Define the routes
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import { Login } from "@src/pages/auth.jsx"
}

route SignupRoute { path: "/signup", to: SignupPage }
page SignupPage {
  component: import { Signup } from "@src/pages/auth.jsx"
}

route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
page RequestPasswordResetPage {
  component: import { RequestPasswordReset } from "@src/pages/auth.jsx",
}

route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
page PasswordResetPage {
  component: import { PasswordReset } from "@src/pages/auth.jsx",
}

route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
page EmailVerificationPage {
  component: import { EmailVerification } from "@src/pages/auth.jsx",
}

We'll define the React components for these pages in the src/pages/auth.tsx file below.

4. Create the Client Pages​

info

We are using Tailwind CSS to style the pages. Read more about how to add it here.

Let's create a auth.tsx file in the src/pages folder and add the following to it:

src/pages/auth.jsx
import {
  LoginForm,
  SignupForm,
  VerifyEmailForm,
  ForgotPasswordForm,
  ResetPasswordForm,
} from 'wasp/client/auth'
import { Link } from 'react-router-dom'

export function Login() {
  return (
    <Layout>
      <LoginForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        Don't have an account yet? <Link to="/signup">go to signup</Link>.
      </span>
      <br />
      <span className="text-sm font-medium text-gray-900">
        Forgot your password? <Link to="/request-password-reset">reset it</Link>
        .
      </span>
    </Layout>
  );
}

export function Signup() {
  return (
    <Layout>
      <SignupForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        I already have an account (<Link to="/login">go to login</Link>).
      </span>
    </Layout>
  );
}

export function EmailVerification() {
  return (
    <Layout>
      <VerifyEmailForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        If everything is okay, <Link to="/login">go to login</Link>
      </span>
    </Layout>
  );
}

export function RequestPasswordReset() {
  return (
    <Layout>
      <ForgotPasswordForm />
    </Layout>
  );
}

export function PasswordReset() {
  return (
    <Layout>
      <ResetPasswordForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        If everything is okay, <Link to="/login">go to login</Link>
      </span>
    </Layout>
  );
}

// A layout component to center the content
export function Layout({ children }) {
  return (
    <div className="w-full h-full bg-white">
      <div className="min-w-full min-h-[75vh] flex items-center justify-center">
        <div className="w-full h-full max-w-sm p-5 bg-white">
          <div>{children}</div>
        </div>
      </div>
    </div>
  );
}

We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

5. Set up an Email Sender​

To support e-mail verification and password reset flows, we need an e-mail sender. Luckily, Wasp supports several email providers out of the box.

We'll use the Dummy provider to speed up the setup. It just logs the emails to the console instead of sending them. You can use any of the supported email providers.

To set up the Dummy provider to send emails, add the following to the main.wasp file:

main.wasp
app myApp {
  // ...
  // 7. Set up the email sender
  emailSender: {
    provider: Dummy,
  }
}

Conclusion​

That's it! We have set up email authentication in our app. 🎉

Running wasp db migrate-dev and then wasp start should give you a working app with email authentication. If you want to put some of the pages behind authentication, read the auth overview.

Login and Signup Flows​

Login​

Auth UI

Signup​

Auth UI

Some of the behavior you get out of the box:

  1. Rate limiting

    We are limiting the rate of sign-up requests to 1 request per minute per email address. This is done to prevent spamming.

  2. Preventing user email leaks

    If somebody tries to signup with an email that already exists and it's verified, we pretend that the account was created instead of saying it's an existing account. This is done to prevent leaking the user's email address.

  3. Allowing registration for unverified emails

    If a user tries to register with an existing but unverified email, we'll allow them to do that. This is done to prevent bad actors from locking out other users from registering with their email address.

  4. Password validation

    Read more about the default password validation rules and how to override them in auth overview docs.

Email Verification Flow​

Automatic email verification in development

In development mode, you can skip the email verification step by setting the SKIP_EMAIL_VERIFICATION_IN_DEV environment variable to true in your .env.server file:

.env.server
SKIP_EMAIL_VERIFICATION_IN_DEV=true

This is useful when you are developing your app and don't want to go through the email verification flow every time you sign up. It can be also useful when you are writing automated tests for your app.

By default, Wasp requires the e-mail to be verified before allowing the user to log in. This is done by sending a verification email to the user's email address and requiring the user to click on a link in the email to verify their email address.

Our setup looks like this:

main.wasp
// ...

emailVerification: {
    clientRoute: EmailVerificationRoute,
}

When the user receives an e-mail, they receive a link that goes to the client route specified in the clientRoute field. In our case, this is the EmailVerificationRoute route we defined in the main.wasp file.

The content of the e-mail can be customized, read more about it here.

Email Verification Page​

We defined our email verification page in the auth.tsx file.

Auth UI

Password Reset Flow​

Users can request a password and then they'll receive an e-mail with a link to reset their password.

Some of the behavior you get out of the box:

  1. Rate limiting

    We are limiting the rate of sign-up requests to 1 request per minute per email address. This is done to prevent spamming.

  2. Preventing user email leaks

    If somebody requests a password reset with an unknown email address, we'll give back the same response as if the user requested a password reset successfully. This is done to prevent leaking information.

Our setup in main.wasp looks like this:

main.wasp
// ...

passwordReset: {
    clientRoute: PasswordResetRoute,
}

Request Password Reset Page​

Users request their password to be reset by going to the /request-password-reset route. We defined our request password reset page in the auth.tsx file.

Request password reset page

Password Reset Page​

When the user receives an e-mail, they receive a link that goes to the client route specified in the clientRoute field. In our case, this is the PasswordResetRoute route we defined in the main.wasp file.

Request password reset page

Users can enter their new password there.

The content of the e-mail can be customized, read more about it here.

Creating a Custom Sign-up Action​

Creating a custom sign-up action

We don't recommend creating a custom sign-up action unless you have a good reason to do so. It is a complex process and you can easily make a mistake that will compromise the security of your app.

The code of your custom sign-up action can look like this:

main.wasp
// ...

action customSignup {
  fn: import { signup } from "@src/auth/signup.js",
}
src/auth/signup.js
import {
  ensurePasswordIsPresent,
  ensureValidPassword,
  ensureValidEmail,
  createProviderId,
  sanitizeAndSerializeProviderData,
  deserializeAndSanitizeProviderData,
  findAuthIdentity,
  createUser,
  createEmailVerificationLink,
  sendEmailVerificationEmail,
} from 'wasp/server/auth'

export const signup = async (args, _context) => {
  ensureValidEmail(args)
  ensurePasswordIsPresent(args)
  ensureValidPassword(args)

  try {
    const providerId = createProviderId('email', args.email)
    const existingAuthIdentity = await findAuthIdentity(providerId)

    if (existingAuthIdentity) {
      const providerData = deserializeAndSanitizeProviderData(existingAuthIdentity.providerData)
      // Your custom code here
    } else {
      // sanitizeAndSerializeProviderData will hash the user's password
      const newUserProviderData = await sanitizeAndSerializeProviderData({
          hashedPassword: args.password,
          isEmailVerified: false,
          emailVerificationSentAt: null,
          passwordResetSentAt: null,
      })
      await createUser(
        providerId,
        providerData,
        // Any additional data you want to store on the User entity
        {},
      )

      // Verification link links to a client route e.g. /email-verification
      const verificationLink = await createEmailVerificationLink(args.email, '/email-verification');
      try {
          await sendEmailVerificationEmail(
              args.email,
              {
                  from: {
                    name: "My App Postman",
                    email: "hello@itsme.com",
                  },
                  to: args.email,
                  subject: "Verify your email",
                  text: `Click the link below to verify your email: ${verificationLink}`,
                  html: `
                      <p>Click the link below to verify your email</p>
                      <a href="${verificationLink}">Verify email</a>
                  `,
              }
          );
      } catch (e: unknown) {
          console.error("Failed to send email verification email:", e);
          throw new HttpError(500, "Failed to send email verification email.");
      } 
    }
  } catch (e) {
    return {
      success: false,
      message: e.message,
    }
  }

  // Your custom code after sign-up.
  // ...

  return {
    success: true,
    message: 'User created successfully',
  }
}

We suggest using the built-in field validators for your authentication flow. You can import them from wasp/server/auth. These are the same validators that Wasp uses internally for the default authentication flow.

Email​

  • ensureValidEmail(args)

    Checks if the email is valid and throws an error if it's not. Read more about the validation rules here.

Password​

  • ensurePasswordIsPresent(args)

    Checks if the password is present and throws an error if it's not.

  • ensureValidPassword(args)

    Checks if the password is valid and throws an error if it's not. Read more about the validation rules here.

Using Auth​

To read more about how to set up the logout button and how to get access to the logged-in user in our client and server code, read the auth overview docs.

getEmail​

If you are looking to access the user's email in your code, you can do that by accessing the info about the user that is stored in the user.auth.identities array.

To make things a bit easier for you, Wasp offers the getEmail helper.

The getEmail helper returns the user's email or null if the user doesn't have an email auth identity.

src/MainPage.jsx
import { getEmail } from 'wasp/auth'

const MainPage = ({ user }) => {
  const email = getEmail(user)
  // ...
}
src/tasks.js
import { getEmail } from 'wasp/auth'

export const createTask = async (args, context) => {
  const email = getEmail(context.user)
  // ...
}

API Reference​

Let's go over the options we can specify when using email authentication.

userEntity fields​

main.wasp
app myApp {
  title: "My app",
  // ...

  auth: {
    userEntity: User,
    methods: {
      email: {
        // We'll explain these options below
      },
    },
    onAuthFailedRedirectTo: "/someRoute"
  },
  // ...
}

entity User {=psl
    id                        Int           @id @default(autoincrement())
psl=}

The user entity needs to have the following fields:

  • id required

    It can be of any type, but it needs to be marked with @id

You can add any other fields you want to the user entity. Make sure to also define them in the userSignupFields field if they need to be set during the sign-up process.

Fields in the email dict​

main.wasp
app myApp {
  title: "My app",
  // ...

  auth: {
    userEntity: User,
    methods: {
      email: {
        userSignupFields: import { userSignupFields } from "@src/auth.js",
        fromField: {
          name: "My App",
          email: "hello@itsme.com"
        },
        emailVerification: {
          clientRoute: EmailVerificationRoute,
          getEmailContentFn: import { getVerificationEmailContent } from "@src/auth/email.js",
        },
        passwordReset: {
          clientRoute: PasswordResetRoute,
          getEmailContentFn: import { getPasswordResetEmailContent } from "@src/auth/email.js",
        },
      },
    },
    onAuthFailedRedirectTo: "/someRoute"
  },
  // ...
}

userSignupFields: ExtImport​

userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

src/auth.js
import { defineUserSignupFields } from 'wasp/server/auth'

export const userSignupFields = defineUserSignupFields({
  address: (data) => {
    if (!data.address) {
      throw new Error('Address is required')
    }
    return data.address
  }
  phone: (data) => data.phone,
})
Read more about the `userSignupFields` function [here](./overview#1-defining-extra-fields).

fromField: EmailFromField required​

fromField is a dict that specifies the name and e-mail address of the sender of the e-mails sent by your app.

It has the following fields:

  • name: name of the sender
  • email: e-mail address of the sender required

emailVerification: EmailVerificationConfig required​

emailVerification is a dict that specifies the details of the e-mail verification process.

It has the following fields:

  • clientRoute: Route: a route that is used for the user to verify their e-mail address. required

    Client route should handle the process of taking a token from the URL and sending it to the server to verify the e-mail address. You can use our verifyEmail action for that.

    src/pages/EmailVerificationPage.jsx
    import { verifyEmail } from 'wasp/client/auth'
    ...
    await verifyEmail({ token });
    note

    We used Auth UI above to avoid doing this work of sending the token to the server manually.

  • getEmailContentFn: ExtImport: a function that returns the content of the e-mail that is sent to the user.

    Defining getEmailContentFn can be done by defining a file in the src directory.

    src/email.js
    export const getVerificationEmailContent = ({ verificationLink }) => ({
      subject: 'Verify your email',
      text: `Click the link below to verify your email: ${verificationLink}`,
      html: `
            <p>Click the link below to verify your email</p>
            <a href="${verificationLink}">Verify email</a>
        `,
    })
    This is the default content of the e-mail, you can customize it to your liking.

passwordReset: PasswordResetConfig required​

passwordReset is a dict that specifies the password reset process.

It has the following fields:

  • clientRoute: Route: a route that is used for the user to reset their password. required

    Client route should handle the process of taking a token from the URL and a new password from the user and sending it to the server. You can use our requestPasswordReset and resetPassword actions to do that.

    src/pages/ForgotPasswordPage.jsx
    import { requestPasswordReset } from 'wasp/client/auth'
    ...
    await requestPasswordReset({ email });
    src/pages/PasswordResetPage.jsx
    import { resetPassword } from 'wasp/client/auth'
    ...
    await resetPassword({ password, token })
    note

    We used Auth UI above to avoid doing this work of sending the password request and the new password to the server manually.

  • getEmailContentFn: ExtImport: a function that returns the content of the e-mail that is sent to the user.

    Defining getEmailContentFn is done by defining a function that looks like this:

    src/email.js
    export const getPasswordResetEmailContent = ({ passwordResetLink }) => ({
      subject: 'Password reset',
      text: `Click the link below to reset your password: ${passwordResetLink}`,
      html: `
            <p>Click the link below to reset your password</p>
            <a href="${passwordResetLink}">Reset password</a>
        `,
    })
    This is the default content of the e-mail, you can customize it to your liking.
- - +
+
Version: 0.12.0

Email

Wasp supports e-mail authentication out of the box, along with email verification and "forgot your password?" flows. It provides you with the server-side implementation and email templates for all of these flows.

Auth UI

Using multiple auth identities for a single user

Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

Setting Up Email Authentication​

We'll need to take the following steps to set up email authentication:

  1. Enable email authentication in the Wasp file
  2. Add the User entity
  3. Add the auth routes and pages
  4. Use Auth UI components in our pages
  5. Set up the email sender

Structure of the main.wasp file we will end up with:

main.wasp
// Configuring e-mail authentication
app myApp {
  auth: { ... }
}

// Defining User entity
entity User { ... }

// Defining routes and pages
route SignupRoute { ... }
page SignupPage { ... }
// ...

1. Enable Email Authentication in main.wasp​

Let's start with adding the following to our main.wasp file:

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    // 1. Specify the user entity (we'll define it next)
    userEntity: User,
    methods: {
      // 2. Enable email authentication
      email: {
        // 3. Specify the email from field
        fromField: {
          name: "My App Postman",
          email: "hello@itsme.com"
        },
        // 4. Specify the email verification and password reset options (we'll talk about them later)
        emailVerification: {
          clientRoute: EmailVerificationRoute,
        },
        passwordReset: {
          clientRoute: PasswordResetRoute,
        },
      },
    },
    onAuthFailedRedirectTo: "/login",
    onAuthSucceededRedirectTo: "/"
  },
}

Read more about the email auth method options here.

2. Add the User Entity​

The User entity can be as simple as including only the id field:

main.wasp
// 5. Define the user entity
entity User {=psl
    id                        Int           @id @default(autoincrement())
    // Add your own fields below
    // ...
psl=}

You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

3. Add the Routes and Pages​

Next, we need to define the routes and pages for the authentication pages.

Add the following to the main.wasp file:

main.wasp
// ...

// 6. Define the routes
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import { Login } from "@src/pages/auth.jsx"
}

route SignupRoute { path: "/signup", to: SignupPage }
page SignupPage {
  component: import { Signup } from "@src/pages/auth.jsx"
}

route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
page RequestPasswordResetPage {
  component: import { RequestPasswordReset } from "@src/pages/auth.jsx",
}

route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
page PasswordResetPage {
  component: import { PasswordReset } from "@src/pages/auth.jsx",
}

route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
page EmailVerificationPage {
  component: import { EmailVerification } from "@src/pages/auth.jsx",
}

We'll define the React components for these pages in the src/pages/auth.tsx file below.

4. Create the Client Pages​

info

We are using Tailwind CSS to style the pages. Read more about how to add it here.

Let's create a auth.tsx file in the src/pages folder and add the following to it:

src/pages/auth.jsx
import {
  LoginForm,
  SignupForm,
  VerifyEmailForm,
  ForgotPasswordForm,
  ResetPasswordForm,
} from 'wasp/client/auth'
import { Link } from 'react-router-dom'

export function Login() {
  return (
    <Layout>
      <LoginForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        Don't have an account yet? <Link to="/signup">go to signup</Link>.
      </span>
      <br />
      <span className="text-sm font-medium text-gray-900">
        Forgot your password? <Link to="/request-password-reset">reset it</Link>
        .
      </span>
    </Layout>
  );
}

export function Signup() {
  return (
    <Layout>
      <SignupForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        I already have an account (<Link to="/login">go to login</Link>).
      </span>
    </Layout>
  );
}

export function EmailVerification() {
  return (
    <Layout>
      <VerifyEmailForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        If everything is okay, <Link to="/login">go to login</Link>
      </span>
    </Layout>
  );
}

export function RequestPasswordReset() {
  return (
    <Layout>
      <ForgotPasswordForm />
    </Layout>
  );
}

export function PasswordReset() {
  return (
    <Layout>
      <ResetPasswordForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        If everything is okay, <Link to="/login">go to login</Link>
      </span>
    </Layout>
  );
}

// A layout component to center the content
export function Layout({ children }) {
  return (
    <div className="w-full h-full bg-white">
      <div className="min-w-full min-h-[75vh] flex items-center justify-center">
        <div className="w-full h-full max-w-sm p-5 bg-white">
          <div>{children}</div>
        </div>
      </div>
    </div>
  );
}

We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

5. Set up an Email Sender​

To support e-mail verification and password reset flows, we need an e-mail sender. Luckily, Wasp supports several email providers out of the box.

We'll use the Dummy provider to speed up the setup. It just logs the emails to the console instead of sending them. You can use any of the supported email providers.

To set up the Dummy provider to send emails, add the following to the main.wasp file:

main.wasp
app myApp {
  // ...
  // 7. Set up the email sender
  emailSender: {
    provider: Dummy,
  }
}

Conclusion​

That's it! We have set up email authentication in our app. 🎉

Running wasp db migrate-dev and then wasp start should give you a working app with email authentication. If you want to put some of the pages behind authentication, read the auth overview.

Login and Signup Flows​

Login​

Auth UI

Signup​

Auth UI

Some of the behavior you get out of the box:

  1. Rate limiting

    We are limiting the rate of sign-up requests to 1 request per minute per email address. This is done to prevent spamming.

  2. Preventing user email leaks

    If somebody tries to signup with an email that already exists and it's verified, we pretend that the account was created instead of saying it's an existing account. This is done to prevent leaking the user's email address.

  3. Allowing registration for unverified emails

    If a user tries to register with an existing but unverified email, we'll allow them to do that. This is done to prevent bad actors from locking out other users from registering with their email address.

  4. Password validation

    Read more about the default password validation rules and how to override them in auth overview docs.

Email Verification Flow​

Automatic email verification in development

In development mode, you can skip the email verification step by setting the SKIP_EMAIL_VERIFICATION_IN_DEV environment variable to true in your .env.server file:

.env.server
SKIP_EMAIL_VERIFICATION_IN_DEV=true

This is useful when you are developing your app and don't want to go through the email verification flow every time you sign up. It can be also useful when you are writing automated tests for your app.

By default, Wasp requires the e-mail to be verified before allowing the user to log in. This is done by sending a verification email to the user's email address and requiring the user to click on a link in the email to verify their email address.

Our setup looks like this:

main.wasp
// ...

emailVerification: {
    clientRoute: EmailVerificationRoute,
}

When the user receives an e-mail, they receive a link that goes to the client route specified in the clientRoute field. In our case, this is the EmailVerificationRoute route we defined in the main.wasp file.

The content of the e-mail can be customized, read more about it here.

Email Verification Page​

We defined our email verification page in the auth.tsx file.

Auth UI

Password Reset Flow​

Users can request a password and then they'll receive an e-mail with a link to reset their password.

Some of the behavior you get out of the box:

  1. Rate limiting

    We are limiting the rate of sign-up requests to 1 request per minute per email address. This is done to prevent spamming.

  2. Preventing user email leaks

    If somebody requests a password reset with an unknown email address, we'll give back the same response as if the user requested a password reset successfully. This is done to prevent leaking information.

Our setup in main.wasp looks like this:

main.wasp
// ...

passwordReset: {
    clientRoute: PasswordResetRoute,
}

Request Password Reset Page​

Users request their password to be reset by going to the /request-password-reset route. We defined our request password reset page in the auth.tsx file.

Request password reset page

Password Reset Page​

When the user receives an e-mail, they receive a link that goes to the client route specified in the clientRoute field. In our case, this is the PasswordResetRoute route we defined in the main.wasp file.

Request password reset page

Users can enter their new password there.

The content of the e-mail can be customized, read more about it here.

Creating a Custom Sign-up Action​

Creating a custom sign-up action

We don't recommend creating a custom sign-up action unless you have a good reason to do so. It is a complex process and you can easily make a mistake that will compromise the security of your app.

The code of your custom sign-up action can look like this:

main.wasp
// ...

action customSignup {
  fn: import { signup } from "@src/auth/signup.js",
}
src/auth/signup.js
import {
  ensurePasswordIsPresent,
  ensureValidPassword,
  ensureValidEmail,
  createProviderId,
  sanitizeAndSerializeProviderData,
  deserializeAndSanitizeProviderData,
  findAuthIdentity,
  createUser,
  createEmailVerificationLink,
  sendEmailVerificationEmail,
} from 'wasp/server/auth'

export const signup = async (args, _context) => {
  ensureValidEmail(args)
  ensurePasswordIsPresent(args)
  ensureValidPassword(args)

  try {
    const providerId = createProviderId('email', args.email)
    const existingAuthIdentity = await findAuthIdentity(providerId)

    if (existingAuthIdentity) {
      const providerData = deserializeAndSanitizeProviderData(existingAuthIdentity.providerData)
      // Your custom code here
    } else {
      // sanitizeAndSerializeProviderData will hash the user's password
      const newUserProviderData = await sanitizeAndSerializeProviderData({
          hashedPassword: args.password,
          isEmailVerified: false,
          emailVerificationSentAt: null,
          passwordResetSentAt: null,
      })
      await createUser(
        providerId,
        providerData,
        // Any additional data you want to store on the User entity
        {},
      )

      // Verification link links to a client route e.g. /email-verification
      const verificationLink = await createEmailVerificationLink(args.email, '/email-verification');
      try {
          await sendEmailVerificationEmail(
              args.email,
              {
                  from: {
                    name: "My App Postman",
                    email: "hello@itsme.com",
                  },
                  to: args.email,
                  subject: "Verify your email",
                  text: `Click the link below to verify your email: ${verificationLink}`,
                  html: `
                      <p>Click the link below to verify your email</p>
                      <a href="${verificationLink}">Verify email</a>
                  `,
              }
          );
      } catch (e: unknown) {
          console.error("Failed to send email verification email:", e);
          throw new HttpError(500, "Failed to send email verification email.");
      } 
    }
  } catch (e) {
    return {
      success: false,
      message: e.message,
    }
  }

  // Your custom code after sign-up.
  // ...

  return {
    success: true,
    message: 'User created successfully',
  }
}

We suggest using the built-in field validators for your authentication flow. You can import them from wasp/server/auth. These are the same validators that Wasp uses internally for the default authentication flow.

Email​

  • ensureValidEmail(args)

    Checks if the email is valid and throws an error if it's not. Read more about the validation rules here.

Password​

  • ensurePasswordIsPresent(args)

    Checks if the password is present and throws an error if it's not.

  • ensureValidPassword(args)

    Checks if the password is valid and throws an error if it's not. Read more about the validation rules here.

Using Auth​

To read more about how to set up the logout button and how to get access to the logged-in user in our client and server code, read the auth overview docs.

getEmail​

If you are looking to access the user's email in your code, you can do that by accessing the info about the user that is stored in the user.auth.identities array.

To make things a bit easier for you, Wasp offers the getEmail helper.

The getEmail helper returns the user's email or null if the user doesn't have an email auth identity.

src/MainPage.jsx
import { getEmail } from 'wasp/auth'

const MainPage = ({ user }) => {
  const email = getEmail(user)
  // ...
}
src/tasks.js
import { getEmail } from 'wasp/auth'

export const createTask = async (args, context) => {
  const email = getEmail(context.user)
  // ...
}

API Reference​

Let's go over the options we can specify when using email authentication.

userEntity fields​

main.wasp
app myApp {
  title: "My app",
  // ...

  auth: {
    userEntity: User,
    methods: {
      email: {
        // We'll explain these options below
      },
    },
    onAuthFailedRedirectTo: "/someRoute"
  },
  // ...
}

entity User {=psl
    id                        Int           @id @default(autoincrement())
psl=}

The user entity needs to have the following fields:

  • id required

    It can be of any type, but it needs to be marked with @id

You can add any other fields you want to the user entity. Make sure to also define them in the userSignupFields field if they need to be set during the sign-up process.

Fields in the email dict​

main.wasp
app myApp {
  title: "My app",
  // ...

  auth: {
    userEntity: User,
    methods: {
      email: {
        userSignupFields: import { userSignupFields } from "@src/auth.js",
        fromField: {
          name: "My App",
          email: "hello@itsme.com"
        },
        emailVerification: {
          clientRoute: EmailVerificationRoute,
          getEmailContentFn: import { getVerificationEmailContent } from "@src/auth/email.js",
        },
        passwordReset: {
          clientRoute: PasswordResetRoute,
          getEmailContentFn: import { getPasswordResetEmailContent } from "@src/auth/email.js",
        },
      },
    },
    onAuthFailedRedirectTo: "/someRoute"
  },
  // ...
}

userSignupFields: ExtImport​

userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

src/auth.js
import { defineUserSignupFields } from 'wasp/server/auth'

export const userSignupFields = defineUserSignupFields({
  address: (data) => {
    if (!data.address) {
      throw new Error('Address is required')
    }
    return data.address
  }
  phone: (data) => data.phone,
})
Read more about the `userSignupFields` function [here](./overview#1-defining-extra-fields).

fromField: EmailFromField required​

fromField is a dict that specifies the name and e-mail address of the sender of the e-mails sent by your app.

It has the following fields:

  • name: name of the sender
  • email: e-mail address of the sender required

emailVerification: EmailVerificationConfig required​

emailVerification is a dict that specifies the details of the e-mail verification process.

It has the following fields:

  • clientRoute: Route: a route that is used for the user to verify their e-mail address. required

    Client route should handle the process of taking a token from the URL and sending it to the server to verify the e-mail address. You can use our verifyEmail action for that.

    src/pages/EmailVerificationPage.jsx
    import { verifyEmail } from 'wasp/client/auth'
    ...
    await verifyEmail({ token });
    note

    We used Auth UI above to avoid doing this work of sending the token to the server manually.

  • getEmailContentFn: ExtImport: a function that returns the content of the e-mail that is sent to the user.

    Defining getEmailContentFn can be done by defining a file in the src directory.

    src/email.js
    export const getVerificationEmailContent = ({ verificationLink }) => ({
      subject: 'Verify your email',
      text: `Click the link below to verify your email: ${verificationLink}`,
      html: `
            <p>Click the link below to verify your email</p>
            <a href="${verificationLink}">Verify email</a>
        `,
    })
    This is the default content of the e-mail, you can customize it to your liking.

passwordReset: PasswordResetConfig required​

passwordReset is a dict that specifies the password reset process.

It has the following fields:

  • clientRoute: Route: a route that is used for the user to reset their password. required

    Client route should handle the process of taking a token from the URL and a new password from the user and sending it to the server. You can use our requestPasswordReset and resetPassword actions to do that.

    src/pages/ForgotPasswordPage.jsx
    import { requestPasswordReset } from 'wasp/client/auth'
    ...
    await requestPasswordReset({ email });
    src/pages/PasswordResetPage.jsx
    import { resetPassword } from 'wasp/client/auth'
    ...
    await resetPassword({ password, token })
    note

    We used Auth UI above to avoid doing this work of sending the password request and the new password to the server manually.

  • getEmailContentFn: ExtImport: a function that returns the content of the e-mail that is sent to the user.

    Defining getEmailContentFn is done by defining a function that looks like this:

    src/email.js
    export const getPasswordResetEmailContent = ({ passwordResetLink }) => ({
      subject: 'Password reset',
      text: `Click the link below to reset your password: ${passwordResetLink}`,
      html: `
            <p>Click the link below to reset your password</p>
            <a href="${passwordResetLink}">Reset password</a>
        `,
    })
    This is the default content of the e-mail, you can customize it to your liking.
+ + \ No newline at end of file diff --git a/docs/0.12.0/auth/entities.html b/docs/0.12.0/auth/entities.html index 439946edbc..33d63d572c 100644 --- a/docs/0.12.0/auth/entities.html +++ b/docs/0.12.0/auth/entities.html @@ -19,13 +19,13 @@ - - + + -
-
Version: 0.12.0

Auth Entities

Wasp supports multiple different authentication methods and for each method, we need to store different information about the user. For example, if you are using the Username & password authentication method, we need to store the user's username and password. On the other hand, if you are using the Email authentication method, you will need to store the user's email, password and for example, their email verification status.

Entities Explained​

To store user information, Wasp creates a few entities behind the scenes. In this section, we will explain what entities are created and how they are connected.

User Entity​

When you want to add authentication to your app, you need to specify the user entity e.g. User in your Wasp file. This entity is a "business logic user" which represents a user of your app.

You can use this entity to store any information about the user that you want to store. For example, you might want to store the user's name or address. You can also use the user entity to define the relations between users and other entities in your app. For example, you might want to define a relation between a user and the tasks that they have created.

entity User {=psl
  id Int @id @default(autoincrement())
  // Any other fields you want to store about the user
psl=}

You own the user entity and you can modify it as you wish. You can add new fields to it, remove fields from it, or change the type of the fields. You can also add new relations to it or remove existing relations from it.

Auth Entities in a Wasp App
Auth Entities in a Wasp App

On the other hand, the Auth, AuthIdentity and Session entities are created behind the scenes and are used to store the user's login credentials. You as the developer don't need to care about this entity most of the time. Wasp owns these entities.

In the case you want to create a custom signup action, you will need to use the Auth and AuthIdentity entities directly.

Example App Model​

Let's imagine we created a simple tasks management app:

  • The app has email and Google-based auth.
  • Users can create tasks and see the tasks that they have created.

Let's look at how would that look in the database:

Example of Auth Entities
Example of Auth Entities

If we take a look at an example user in the database, we can see:

  • The business logic user, User is connected to multiple Task entities.
    • In this example, "Example User" has two tasks.
  • The User is connected to exactly one Auth entity.
  • Each Auth entity can have multiple AuthIdentity entities.
    • In this example, the Auth entity has two AuthIdentity entities: one for the email-based auth and one for the Google-based auth.
  • Each Auth entity can have multiple Session entities.
    • In this example, the Auth entity has one Session entity.
Using multiple auth identities for a single user

Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

Auth Entity internal​

Wasp's internal Auth entity is used to connect the business logic user, User with the user's login credentials.

entity Auth {=psl
  id         String         @id @default(uuid())
  userId     Int?           @unique
  // Wasp injects this relation on the User entity as well
  user       User?          @relation(fields: [userId], references: [id], onDelete: Cascade) 
  identities AuthIdentity[]
  sessions   Session[]
psl=}

The Auth fields:

  • id is a unique identifier of the Auth entity.
  • userId is a foreign key to the User entity.
    • It is used to connect the Auth entity with the business logic user.
  • user is a relation to the User entity.
    • This relation is injected on the User entity as well.
  • identities is a relation to the AuthIdentity entity.
  • sessions is a relation to the Session entity.

AuthIdentity Entity internal​

The AuthIdentity entity is used to store the user's login credentials for various authentication methods.

entity AuthIdentity {=psl
  providerName   String
  providerUserId String
  providerData   String @default("{}")
  authId         String
  auth           Auth   @relation(fields: [authId], references: [id], onDelete: Cascade)

  @@id([providerName, providerUserId])  
psl=}

The AuthIdentity fields:

  • providerName is the name of the authentication provider.
    • For example, email or google.
  • providerUserId is the user's ID in the authentication provider.
    • For example, the user's email or Google ID.
  • providerData is a JSON string that contains additional data about the user from the authentication provider.
  • authId is a foreign key to the Auth entity.
    • It is used to connect the AuthIdentity entity with the Auth entity.
  • auth is a relation to the Auth entity.

Session Entity internal​

The Session entity is used to store the user's session information. It is used to keep the user logged in between page refreshes.

entity Session {=psl
  id        String   @id @unique
  expiresAt DateTime
  userId    String
  auth      Auth     @relation(references: [id], fields: [userId], onDelete: Cascade)

  @@index([userId])
psl=}

The Session fields:

  • id is a unique identifier of the Session entity.
  • expiresAt is the date when the session expires.
  • userId is a foreign key to the Auth entity.
    • It is used to connect the Session entity with the Auth entity.
  • auth is a relation to the Auth entity.

Accessing the Auth Fields​

If you are looking to access the user's email or username in your code, you can do that by accessing the info about the user that is stored in the AuthIdentity entity.

Everywhere where Wasp gives you the user object, it also includes the auth relation with the identities relation. This means that you can access the auth identity info by using the user.auth.identities array.

To make things a bit easier for you, Wasp offers a few helper functions that you can use to access the auth identity info.

getEmail​

The getEmail helper returns the user's email or null if the user doesn't have an email auth identity.

src/MainPage.jsx
import { getEmail } from 'wasp/auth'

const MainPage = ({ user }) => {
  const email = getEmail(user)
  // ...
}
src/tasks.js
import { getEmail } from 'wasp/auth'

export const createTask = async (args, context) => {
  const email = getEmail(context.user)
  // ...
}

getUsername​

The getUsername helper returns the user's username or null if the user doesn't have a username auth identity.

src/MainPage.jsx
import { getUsername } from 'wasp/auth'

const MainPage = ({ user }) => {
  const username = getUsername(user)
  // ...
}
src/tasks.js
import { getUsername } from 'wasp/auth'

export const createTask = async (args, context) => {
  const username = getUsername(context.user)
  // ...
}

getFirstProviderUserId​

The getFirstProviderUserId helper returns the first user ID (e.g. username or email) that it finds for the user or null if it doesn't find any.

As mentioned before, the providerUserId field is how providers identify our users. For example, the user's username in the case of the username auth or the user's email in the case of the email auth. This can be useful if you support multiple authentication methods and you need any ID that identifies the user in your app.

src/MainPage.jsx
import { getFirstProviderUserId } from 'wasp/auth'

const MainPage = ({ user }) => {
  const userId = getFirstProviderUserId(user)
  // ...
}
src/tasks.js
import { getFirstProviderUserId } from 'wasp/auth'

export const createTask = async (args, context) => {
  const userId = getFirstProviderUserId(context.user)
  // ...
}

findUserIdentity​

You can find a specific auth identity by using the findUserIdentity helper function. This function takes a user and a providerName and returns the first providerName identity that it finds or null if it doesn't find any.

Possible provider names are:

  • email
  • username
  • google
  • github

This can be useful if you want to check if the user has a specific auth identity. For example, you might want to check if the user has an email auth identity or Google auth identity.

src/MainPage.jsx
import { findUserIdentity } from 'wasp/auth'

const MainPage = ({ user }) => {
  const emailIdentity = findUserIdentity(user, 'email')
  const googleIdentity = findUserIdentity(user, 'google')
  if (emailIdentity) {
    // ...
  } else if (googleIdentity) {
    // ...
  }
  // ...
}
src/tasks.js
import { findUserIdentity } from 'wasp/client/auth'

export const createTask = async (args, context) => {
  const emailIdentity = findUserIdentity(context.user, 'email')
  const googleIdentity = findUserIdentity(context.user, 'google')
  if (emailIdentity) {
    // ...
  } else if (googleIdentity) {
    // ...
  }
  // ...
}

Custom Signup Action​

Let's take a look at how you can use the Auth and AuthIdentity entities to create custom login and signup actions. For example, you might want to create a custom signup action that creates a user in your app and also creates a user in a third-party service.

Custom Signup Examples

In the Email section of the docs we give you an example for custom email signup and in the Username & password section of the docs we give you an example for custom username & password signup.

Below is a simplified version of a custom signup action which you probably wouldn't use in your app but it shows you how you can use the Auth and AuthIdentity entities to create a custom signup action.

main.wasp
// ...

action customSignup {
  fn: import { signup } from "@src/auth/signup.js",
  entities: [User]
}
src/auth/signup.js
import {
  createProviderId,
  sanitizeAndSerializeProviderData,
  createUser,
} from 'wasp/server/auth'

export const signup = async (args, { entities: { User } }) => {
  try {
    // Provider ID is a combination of the provider name and the provider user ID
    // And it is used to uniquely identify the user in your app
    const providerId = createProviderId('username', args.username)
    // sanitizeAndSerializeProviderData hashes the password and returns a JSON string
    const providerData = await sanitizeAndSerializeProviderData({
      hashedPassword: args.password,
    })

    await createUser(
      providerId,
      providerData,
      // Any additional data you want to store on the User entity
      {},
    )

    // This is equivalent to:
    // await User.create({
    //   data: {
    //     auth: {
    //       create: {
    //         identities: {
    //             create: {
    //                 providerName: 'username',
    //                 providerUserId: args.username
    //                 providerData,
    //             },
    //         },
    //       }
    //     },
    //   }
    // })
  } catch (e) {
    return {
      success: false,
      message: e.message,
    }
  }

  // Your custom code after sign-up.
  // ...

  return {
    success: true,
    message: 'User created successfully',
  }
}

You can use whichever method suits your needs better: either the createUser function or Prisma's User.create method. The createUser function is a bit more convenient to use because it hides some of the complexity. On the other hand, the User.create method gives you more control over the data that is stored in the Auth and AuthIdentity entities.

- - +
+
Version: 0.12.0

Auth Entities

Wasp supports multiple different authentication methods and for each method, we need to store different information about the user. For example, if you are using the Username & password authentication method, we need to store the user's username and password. On the other hand, if you are using the Email authentication method, you will need to store the user's email, password and for example, their email verification status.

Entities Explained​

To store user information, Wasp creates a few entities behind the scenes. In this section, we will explain what entities are created and how they are connected.

User Entity​

When you want to add authentication to your app, you need to specify the user entity e.g. User in your Wasp file. This entity is a "business logic user" which represents a user of your app.

You can use this entity to store any information about the user that you want to store. For example, you might want to store the user's name or address. You can also use the user entity to define the relations between users and other entities in your app. For example, you might want to define a relation between a user and the tasks that they have created.

entity User {=psl
  id Int @id @default(autoincrement())
  // Any other fields you want to store about the user
psl=}

You own the user entity and you can modify it as you wish. You can add new fields to it, remove fields from it, or change the type of the fields. You can also add new relations to it or remove existing relations from it.

Auth Entities in a Wasp App
Auth Entities in a Wasp App

On the other hand, the Auth, AuthIdentity and Session entities are created behind the scenes and are used to store the user's login credentials. You as the developer don't need to care about this entity most of the time. Wasp owns these entities.

In the case you want to create a custom signup action, you will need to use the Auth and AuthIdentity entities directly.

Example App Model​

Let's imagine we created a simple tasks management app:

  • The app has email and Google-based auth.
  • Users can create tasks and see the tasks that they have created.

Let's look at how would that look in the database:

Example of Auth Entities
Example of Auth Entities

If we take a look at an example user in the database, we can see:

  • The business logic user, User is connected to multiple Task entities.
    • In this example, "Example User" has two tasks.
  • The User is connected to exactly one Auth entity.
  • Each Auth entity can have multiple AuthIdentity entities.
    • In this example, the Auth entity has two AuthIdentity entities: one for the email-based auth and one for the Google-based auth.
  • Each Auth entity can have multiple Session entities.
    • In this example, the Auth entity has one Session entity.
Using multiple auth identities for a single user

Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

Auth Entity internal​

Wasp's internal Auth entity is used to connect the business logic user, User with the user's login credentials.

entity Auth {=psl
  id         String         @id @default(uuid())
  userId     Int?           @unique
  // Wasp injects this relation on the User entity as well
  user       User?          @relation(fields: [userId], references: [id], onDelete: Cascade) 
  identities AuthIdentity[]
  sessions   Session[]
psl=}

The Auth fields:

  • id is a unique identifier of the Auth entity.
  • userId is a foreign key to the User entity.
    • It is used to connect the Auth entity with the business logic user.
  • user is a relation to the User entity.
    • This relation is injected on the User entity as well.
  • identities is a relation to the AuthIdentity entity.
  • sessions is a relation to the Session entity.

AuthIdentity Entity internal​

The AuthIdentity entity is used to store the user's login credentials for various authentication methods.

entity AuthIdentity {=psl
  providerName   String
  providerUserId String
  providerData   String @default("{}")
  authId         String
  auth           Auth   @relation(fields: [authId], references: [id], onDelete: Cascade)

  @@id([providerName, providerUserId])  
psl=}

The AuthIdentity fields:

  • providerName is the name of the authentication provider.
    • For example, email or google.
  • providerUserId is the user's ID in the authentication provider.
    • For example, the user's email or Google ID.
  • providerData is a JSON string that contains additional data about the user from the authentication provider.
  • authId is a foreign key to the Auth entity.
    • It is used to connect the AuthIdentity entity with the Auth entity.
  • auth is a relation to the Auth entity.

Session Entity internal​

The Session entity is used to store the user's session information. It is used to keep the user logged in between page refreshes.

entity Session {=psl
  id        String   @id @unique
  expiresAt DateTime
  userId    String
  auth      Auth     @relation(references: [id], fields: [userId], onDelete: Cascade)

  @@index([userId])
psl=}

The Session fields:

  • id is a unique identifier of the Session entity.
  • expiresAt is the date when the session expires.
  • userId is a foreign key to the Auth entity.
    • It is used to connect the Session entity with the Auth entity.
  • auth is a relation to the Auth entity.

Accessing the Auth Fields​

If you are looking to access the user's email or username in your code, you can do that by accessing the info about the user that is stored in the AuthIdentity entity.

Everywhere where Wasp gives you the user object, it also includes the auth relation with the identities relation. This means that you can access the auth identity info by using the user.auth.identities array.

To make things a bit easier for you, Wasp offers a few helper functions that you can use to access the auth identity info.

getEmail​

The getEmail helper returns the user's email or null if the user doesn't have an email auth identity.

src/MainPage.jsx
import { getEmail } from 'wasp/auth'

const MainPage = ({ user }) => {
  const email = getEmail(user)
  // ...
}
src/tasks.js
import { getEmail } from 'wasp/auth'

export const createTask = async (args, context) => {
  const email = getEmail(context.user)
  // ...
}

getUsername​

The getUsername helper returns the user's username or null if the user doesn't have a username auth identity.

src/MainPage.jsx
import { getUsername } from 'wasp/auth'

const MainPage = ({ user }) => {
  const username = getUsername(user)
  // ...
}
src/tasks.js
import { getUsername } from 'wasp/auth'

export const createTask = async (args, context) => {
  const username = getUsername(context.user)
  // ...
}

getFirstProviderUserId​

The getFirstProviderUserId helper returns the first user ID (e.g. username or email) that it finds for the user or null if it doesn't find any.

As mentioned before, the providerUserId field is how providers identify our users. For example, the user's username in the case of the username auth or the user's email in the case of the email auth. This can be useful if you support multiple authentication methods and you need any ID that identifies the user in your app.

src/MainPage.jsx
import { getFirstProviderUserId } from 'wasp/auth'

const MainPage = ({ user }) => {
  const userId = getFirstProviderUserId(user)
  // ...
}
src/tasks.js
import { getFirstProviderUserId } from 'wasp/auth'

export const createTask = async (args, context) => {
  const userId = getFirstProviderUserId(context.user)
  // ...
}

findUserIdentity​

You can find a specific auth identity by using the findUserIdentity helper function. This function takes a user and a providerName and returns the first providerName identity that it finds or null if it doesn't find any.

Possible provider names are:

  • email
  • username
  • google
  • github

This can be useful if you want to check if the user has a specific auth identity. For example, you might want to check if the user has an email auth identity or Google auth identity.

src/MainPage.jsx
import { findUserIdentity } from 'wasp/auth'

const MainPage = ({ user }) => {
  const emailIdentity = findUserIdentity(user, 'email')
  const googleIdentity = findUserIdentity(user, 'google')
  if (emailIdentity) {
    // ...
  } else if (googleIdentity) {
    // ...
  }
  // ...
}
src/tasks.js
import { findUserIdentity } from 'wasp/client/auth'

export const createTask = async (args, context) => {
  const emailIdentity = findUserIdentity(context.user, 'email')
  const googleIdentity = findUserIdentity(context.user, 'google')
  if (emailIdentity) {
    // ...
  } else if (googleIdentity) {
    // ...
  }
  // ...
}

Custom Signup Action​

Let's take a look at how you can use the Auth and AuthIdentity entities to create custom login and signup actions. For example, you might want to create a custom signup action that creates a user in your app and also creates a user in a third-party service.

Custom Signup Examples

In the Email section of the docs we give you an example for custom email signup and in the Username & password section of the docs we give you an example for custom username & password signup.

Below is a simplified version of a custom signup action which you probably wouldn't use in your app but it shows you how you can use the Auth and AuthIdentity entities to create a custom signup action.

main.wasp
// ...

action customSignup {
  fn: import { signup } from "@src/auth/signup.js",
  entities: [User]
}
src/auth/signup.js
import {
  createProviderId,
  sanitizeAndSerializeProviderData,
  createUser,
} from 'wasp/server/auth'

export const signup = async (args, { entities: { User } }) => {
  try {
    // Provider ID is a combination of the provider name and the provider user ID
    // And it is used to uniquely identify the user in your app
    const providerId = createProviderId('username', args.username)
    // sanitizeAndSerializeProviderData hashes the password and returns a JSON string
    const providerData = await sanitizeAndSerializeProviderData({
      hashedPassword: args.password,
    })

    await createUser(
      providerId,
      providerData,
      // Any additional data you want to store on the User entity
      {},
    )

    // This is equivalent to:
    // await User.create({
    //   data: {
    //     auth: {
    //       create: {
    //         identities: {
    //             create: {
    //                 providerName: 'username',
    //                 providerUserId: args.username
    //                 providerData,
    //             },
    //         },
    //       }
    //     },
    //   }
    // })
  } catch (e) {
    return {
      success: false,
      message: e.message,
    }
  }

  // Your custom code after sign-up.
  // ...

  return {
    success: true,
    message: 'User created successfully',
  }
}

You can use whichever method suits your needs better: either the createUser function or Prisma's User.create method. The createUser function is a bit more convenient to use because it hides some of the complexity. On the other hand, the User.create method gives you more control over the data that is stored in the Auth and AuthIdentity entities.

+ + \ No newline at end of file diff --git a/docs/0.12.0/auth/overview.html b/docs/0.12.0/auth/overview.html index ee9f8b918e..bdc46a140e 100644 --- a/docs/0.12.0/auth/overview.html +++ b/docs/0.12.0/auth/overview.html @@ -19,15 +19,15 @@ - - + + -
-
Version: 0.12.0

Overview

Auth is an essential piece of any serious application. That's why Wasp provides authentication and authorization support out of the box.

Here's a 1-minute tour of how full-stack auth works in Wasp:

Enabling auth for your app is optional and can be done by configuring the auth field of your app declaration:

main.wasp
app MyApp {
  title: "My app",
  //...
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {}, // use this or email, not both
      email: {}, // use this or usernameAndPassword, not both
      google: {},
      gitHub: {},
    },
    onAuthFailedRedirectTo: "/someRoute"
  }
}

//...

Read more about the auth field options in the API Reference section.

We will provide a quick overview of auth in Wasp and link to more detailed documentation for each auth method.

Available auth methods​

Wasp supports the following auth methods:

Email »

Email verification, password reset, etc.

Username & Password »

The simplest way to get started

Google »

Users sign in with their Google account

Github »

Users sign in with their Github account

Keycloak »

Users sign in with their Keycloak account

Click on each auth method for more details.

Let's say we enabled the Username & password authentication.

We get an auth backend with signup and login endpoints. We also get the user object in our Operations and we can decide what to do based on whether the user is logged in or not.

We would also get the Auth UI generated for us. We can set up our login and signup pages where our users can create their account and login. We can then protect certain pages by setting authRequired: true for them. This will make sure that only logged-in users can access them.

We will also have access to the user object in our frontend code, so we can show different UI to logged-in and logged-out users. For example, we can show the user's name in the header alongside a logout button or a login button if the user is not logged in.

Protecting a page with authRequired​

When declaring a page, you can set the authRequired property.

If you set it to true, only authenticated users can access the page. Unauthenticated users are redirected to a route defined by the app.auth.onAuthFailedRedirectTo field.

main.wasp
page MainPage {
  component: import Main from "@src/pages/Main",
  authRequired: true
}
Requires auth method

You can only use authRequired if your app uses one of the available auth methods.

If authRequired is set to true, the page's React component (specified by the component property) receives the user object as a prop. Read more about the user object in the Accessing the logged-in user section.

Logout action​

We provide an action for logging out the user. Here's how you can use it:

src/components/LogoutButton.jsx
import { logout } from 'wasp/client/auth'

const LogoutButton = () => {
  return <button onClick={logout}>Logout</button>
}

Accessing the logged-in user​

You can get access to the user object both on the server and on the client. The user object contains the logged-in user's data.

The user object has all the fields that you defined in your User entity, plus the auth field which contains the auth identities connected to the user. For example, if the user signed up with their email, the user object might look something like this:

const user = {
  id: "19c7d164-b5cb-4dde-a0cc-0daea77cf854",

  // Your entity's fields.
  address: "My address",
  // ...

  // Auth identities connected to the user.
  auth: {
    id: "26ab6f96-ed76-4ee5-9ac3-2fd0bf19711f",
    identities: [
      {
        providerName: "email",
        providerUserId: "some@email.com",
        providerData: { ... },
      },
    ]
  },
}

You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

On the client​

There are two ways to access the user object on the client:

  • the user prop
  • the useAuth hook

Using the user prop​

If the page's declaration sets authRequired to true, the page's React component receives the user object as a prop:

main.wasp
// ...

page AccountPage {
  component: import Account from "@src/pages/Account",
  authRequired: true
}
src/pages/Account.jsx
import Button from './Button'
import { logout } from 'wasp/client/auth'

const AccountPage = ({ user }) => {
  return (
    <div>
      <Button onClick={logout}>Logout</Button>
      {JSON.stringify(user, null, 2)}
    </div>
  )
}

export default AccountPage

Using the useAuth hook​

Wasp provides a React hook you can use in the client components - useAuth.

This hook is a thin wrapper over Wasp's useQuery hook and returns data in the same format.

src/pages/MainPage.jsx
import { useAuth, logout } from 'wasp/client/auth'
import { Link } from 'react-router-dom'
import Todo from '../Todo'

export function Main() {
  const { data: user } = useAuth()

  if (!user) {
    return (
      <span>
        Please <Link to="/login">login</Link> or{' '}
        <Link to="/signup">sign up</Link>.
      </span>
    )
  } else {
    return (
      <>
        <button onClick={logout}>Logout</button>
        <Todo />
      </>
    )
  }
}
tip

Since the user prop is only available in a page's React component: use the user prop in the page's React component and the useAuth hook in any other React component.

On the server​

Using the context.user object​

When authentication is enabled, all queries and actions have access to the user object through the context argument. context.user contains all User entity's fields and the auth identities connected to the user. We strip out the hashedPassword field from the identities for security reasons.

src/actions.js
import { HttpError } from 'wasp/server'

export const createTask = async (task, context) => {
  if (!context.user) {
    throw new HttpError(403)
  }

  const Task = context.entities.Task
  return Task.create({
    data: {
      description: task.description,
      user: {
        connect: { id: context.user.id },
      },
    },
  })
}

To implement access control in your app, each operation must check context.user and decide what to do. For example, if context.user is undefined inside a private operation, the user's access should be denied.

When using WebSockets, the user object is also available on the socket.data object. Read more in the WebSockets section.

Sessions​

Wasp's auth uses sessions to keep track of the logged-in user. The session is stored in localStorage on the client and in the database on the server. Under the hood, Wasp uses the excellent Lucia Auth v3 library for session management.

When users log in, Wasp creates a session for them and stores it in the database. The session is then sent to the client and stored in localStorage. When users log out, Wasp deletes the session from the database and from localStorage.

User Entity​

Password Hashing​

If you are saving a user's password in the database, you should never save it as plain text. You can use Wasp's helper functions for serializing and deserializing provider data which will automatically hash the password for you:

main.wasp
// ...

action updatePassword {
  fn: import { updatePassword } from "@src/auth",
}
src/auth.js
import {
  createProviderId,
  findAuthIdentity,
  updateAuthIdentityProviderData,
  deserializeAndSanitizeProviderData,
} from 'wasp/server/auth';

export const updatePassword = async (args, context) => {
  const providerId = createProviderId('email', args.email)
  const authIdentity = await findAuthIdentity(providerId)
  if (!authIdentity) {
      throw new HttpError(400, "Unknown user")
  }
  
  const providerData = deserializeAndSanitizeProviderData(authIdentity.providerData)

  // Updates the password and hashes it automatically.
  await updateAuthIdentityProviderData(providerId, providerData, {
      hashedPassword: args.password,
  })
}

Default Validations​

When you are using the default authentication flow, Wasp validates the fields with some default validations. These validations run if you use Wasp's built-in Auth UI or if you use the provided auth actions.

If you decide to create your custom auth actions, you'll need to run the validations yourself.

Default validations depend on the auth method you use.

Username & Password​

If you use Username & password authentication, the default validations are:

  • The username must not be empty
  • The password must not be empty, have at least 8 characters, and contain a number

Note that usernames are stored in a case-insensitive manner.

Email​

If you use Email authentication, the default validations are:

  • The email must not be empty and a valid email address
  • The password must not be empty, have at least 8 characters, and contain a number

Note that emails are stored in a case-insensitive manner.

Customizing the Signup Process​

Sometimes you want to include extra fields in your signup process, like first name and last name and save them in the User entity.

For this to happen:

  • you need to define the fields that you want saved in the database,
  • you need to customize the SignupForm (in the case of Email or Username & Password auth)

Other times, you might need to just add some extra UI elements to the form, like a checkbox for terms of service. In this case, customizing only the UI components is enough.

Let's see how to do both.

1. Defining Extra Fields​

If we want to save some extra fields in our signup process, we need to tell our app they exist.

We do that by defining an object where the keys represent the field name, and the values are functions that receive the data sent from the client* and return the value of the field.

* We exclude the password field from this object to prevent it from being saved as plain-text in the database. The password field is handled by Wasp's auth backend.

First, we add the auth.methods.{authMethod}.userSignupFields field in our main.wasp file. The {authMethod} depends on the auth method you are using.

For example, if you are using Username & Password, you would add the auth.methods.usernameAndPassword.userSignupFields field:

main.wasp
app crudTesting {
  // ...
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {
        userSignupFields: import { userSignupFields } from "@src/auth/signup",
      },
    },
    onAuthFailedRedirectTo: "/login",
  },
}

entity User {=psl
  id Int @id @default(autoincrement())
  address String?
psl=}

Then we'll define the userSignupFields object in the src/auth/signup.js file:

src/auth/signup.js
import { defineUserSignupFields } from 'wasp/server/auth'

export const userSignupFields = defineUserSignupFields({
  address: async (data) => {
    const address = data.address
    if (typeof address !== 'string') {
      throw new Error('Address is required')
    }
    if (address.length < 5) {
      throw new Error('Address must be at least 5 characters long')
    }
    return address
  },
})

Read more about the userSignupFields object in the API Reference.

Keep in mind, that these field names need to exist on the userEntity you defined in your main.wasp file e.g. address needs to be a field on the User entity.

The field function will receive the data sent from the client and it needs to return the value that will be saved into the database. If the field is invalid, the function should throw an error.

Using Validation Libraries

You can use any validation library you want to validate the fields. For example, you can use zod like this:

Click to see the code
src/auth/signup.js
import { defineUserSignupFields } from 'wasp/server/auth'
import * as z from 'zod'

export const userSignupFields = defineUserSignupFields({
  address: (data) => {
    const AddressSchema = z
      .string({
        required_error: 'Address is required',
        invalid_type_error: 'Address must be a string',
      })
      .min(10, 'Address must be at least 10 characters long')
    const result = AddressSchema.safeParse(data.address)
    if (result.success === false) {
      throw new Error(result.error.issues[0].message)
    }
    return result.data
  },
})

Now that we defined the fields, Wasp knows how to:

  1. Validate the data sent from the client
  2. Save the data to the database

Next, let's see how to customize Auth UI to include those fields.

2. Customizing the Signup Component​

Using Custom Signup Component

If you are not using Wasp's Auth UI, you can skip this section. Just make sure to include the extra fields in your custom signup form.

Read more about using the signup actions for:

  • email auth here
  • username & password auth here

If you are using Wasp's Auth UI, you can customize the SignupForm component by passing the additionalFields prop to it. It can be either a list of extra fields or a render function.

Using a List of Extra Fields​

When you pass in a list of extra fields to the SignupForm, they are added to the form one by one, in the order you pass them in.

Inside the list, there can be either objects or render functions (you can combine them):

  1. Objects are a simple way to describe new fields you need, but a bit less flexible than render functions.
  2. Render functions can be used to render any UI you want, but they require a bit more code. The render functions receive the react-hook-form object and the form state object as arguments.
src/SignupPage.jsx
import {
  SignupForm,
  FormError,
  FormInput,
  FormItemGroup,
  FormLabel,
} from 'wasp/client/auth'

export const SignupPage = () => {
  return (
    <SignupForm
      additionalFields={[
        /* The address field is defined using an object */
        {
          name: 'address',
          label: 'Address',
          type: 'input',
          validations: {
            required: 'Address is required',
          },
        },
        /* The phone number is defined using a render function */
        (form, state) => {
          return (
            <FormItemGroup>
              <FormLabel>Phone Number</FormLabel>
              <FormInput
                {...form.register('phoneNumber', {
                  required: 'Phone number is required',
                })}
                disabled={state.isLoading}
              />
              {form.formState.errors.phoneNumber && (
                <FormError>
                  {form.formState.errors.phoneNumber.message}
                </FormError>
              )}
            </FormItemGroup>
          )
        },
      ]}
    />
  )
}

Read more about the extra fields in the API Reference.

Using a Single Render Function​

Instead of passing in a list of extra fields, you can pass in a render function which will receive the react-hook-form object and the form state object as arguments. What ever the render function returns, will be rendered below the default fields.

src/SignupPage.jsx
import { SignupForm, FormItemGroup } from 'wasp/client/auth'

export const SignupPage = () => {
  return (
    <SignupForm
      additionalFields={(form, state) => {
        const username = form.watch('username')
        return (
          username && (
            <FormItemGroup>
              Hello there <strong>{username}</strong> 👋
            </FormItemGroup>
          )
        )
      }}
    />
  )
}

Read more about the render function in the API Reference.

API Reference​

Auth Fields​

main.wasp
  title: "My app",
  //...
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {}, // use this or email, not both
      email: {}, // use this or usernameAndPassword, not both
      google: {},
      gitHub: {},
    },
    onAuthFailedRedirectTo: "/someRoute",
    signup: { ... }
  }
}

//...

app.auth is a dictionary with the following fields:

userEntity: entity required​

The entity representing the user connected to your business logic.

You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

methods: dict required​

A dictionary of auth methods enabled for the app.

Email »

Email verification, password reset, etc.

Username & Password »

The simplest way to get started

Google »

Users sign in with their Google account

Github »

Users sign in with their Github account

Keycloak »

Users sign in with their Keycloak account

Click on each auth method for more details.

onAuthFailedRedirectTo: String required​

The route to which Wasp should redirect unauthenticated user when they try to access a private page (i.e., a page that has authRequired: true). +

+
Version: 0.12.0

Overview

Auth is an essential piece of any serious application. That's why Wasp provides authentication and authorization support out of the box.

Here's a 1-minute tour of how full-stack auth works in Wasp:

Enabling auth for your app is optional and can be done by configuring the auth field of your app declaration:

main.wasp
app MyApp {
  title: "My app",
  //...
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {}, // use this or email, not both
      email: {}, // use this or usernameAndPassword, not both
      google: {},
      gitHub: {},
    },
    onAuthFailedRedirectTo: "/someRoute"
  }
}

//...

Read more about the auth field options in the API Reference section.

We will provide a quick overview of auth in Wasp and link to more detailed documentation for each auth method.

Available auth methods​

Wasp supports the following auth methods:

Email »

Email verification, password reset, etc.

Username & Password »

The simplest way to get started

Google »

Users sign in with their Google account

Github »

Users sign in with their Github account

Keycloak »

Users sign in with their Keycloak account

Click on each auth method for more details.

Let's say we enabled the Username & password authentication.

We get an auth backend with signup and login endpoints. We also get the user object in our Operations and we can decide what to do based on whether the user is logged in or not.

We would also get the Auth UI generated for us. We can set up our login and signup pages where our users can create their account and login. We can then protect certain pages by setting authRequired: true for them. This will make sure that only logged-in users can access them.

We will also have access to the user object in our frontend code, so we can show different UI to logged-in and logged-out users. For example, we can show the user's name in the header alongside a logout button or a login button if the user is not logged in.

Protecting a page with authRequired​

When declaring a page, you can set the authRequired property.

If you set it to true, only authenticated users can access the page. Unauthenticated users are redirected to a route defined by the app.auth.onAuthFailedRedirectTo field.

main.wasp
page MainPage {
  component: import Main from "@src/pages/Main",
  authRequired: true
}
Requires auth method

You can only use authRequired if your app uses one of the available auth methods.

If authRequired is set to true, the page's React component (specified by the component property) receives the user object as a prop. Read more about the user object in the Accessing the logged-in user section.

Logout action​

We provide an action for logging out the user. Here's how you can use it:

src/components/LogoutButton.jsx
import { logout } from 'wasp/client/auth'

const LogoutButton = () => {
  return <button onClick={logout}>Logout</button>
}

Accessing the logged-in user​

You can get access to the user object both on the server and on the client. The user object contains the logged-in user's data.

The user object has all the fields that you defined in your User entity, plus the auth field which contains the auth identities connected to the user. For example, if the user signed up with their email, the user object might look something like this:

const user = {
  id: "19c7d164-b5cb-4dde-a0cc-0daea77cf854",

  // Your entity's fields.
  address: "My address",
  // ...

  // Auth identities connected to the user.
  auth: {
    id: "26ab6f96-ed76-4ee5-9ac3-2fd0bf19711f",
    identities: [
      {
        providerName: "email",
        providerUserId: "some@email.com",
        providerData: { ... },
      },
    ]
  },
}

You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

On the client​

There are two ways to access the user object on the client:

  • the user prop
  • the useAuth hook

Using the user prop​

If the page's declaration sets authRequired to true, the page's React component receives the user object as a prop:

main.wasp
// ...

page AccountPage {
  component: import Account from "@src/pages/Account",
  authRequired: true
}
src/pages/Account.jsx
import Button from './Button'
import { logout } from 'wasp/client/auth'

const AccountPage = ({ user }) => {
  return (
    <div>
      <Button onClick={logout}>Logout</Button>
      {JSON.stringify(user, null, 2)}
    </div>
  )
}

export default AccountPage

Using the useAuth hook​

Wasp provides a React hook you can use in the client components - useAuth.

This hook is a thin wrapper over Wasp's useQuery hook and returns data in the same format.

src/pages/MainPage.jsx
import { useAuth, logout } from 'wasp/client/auth'
import { Link } from 'react-router-dom'
import Todo from '../Todo'

export function Main() {
  const { data: user } = useAuth()

  if (!user) {
    return (
      <span>
        Please <Link to="/login">login</Link> or{' '}
        <Link to="/signup">sign up</Link>.
      </span>
    )
  } else {
    return (
      <>
        <button onClick={logout}>Logout</button>
        <Todo />
      </>
    )
  }
}
tip

Since the user prop is only available in a page's React component: use the user prop in the page's React component and the useAuth hook in any other React component.

On the server​

Using the context.user object​

When authentication is enabled, all queries and actions have access to the user object through the context argument. context.user contains all User entity's fields and the auth identities connected to the user. We strip out the hashedPassword field from the identities for security reasons.

src/actions.js
import { HttpError } from 'wasp/server'

export const createTask = async (task, context) => {
  if (!context.user) {
    throw new HttpError(403)
  }

  const Task = context.entities.Task
  return Task.create({
    data: {
      description: task.description,
      user: {
        connect: { id: context.user.id },
      },
    },
  })
}

To implement access control in your app, each operation must check context.user and decide what to do. For example, if context.user is undefined inside a private operation, the user's access should be denied.

When using WebSockets, the user object is also available on the socket.data object. Read more in the WebSockets section.

Sessions​

Wasp's auth uses sessions to keep track of the logged-in user. The session is stored in localStorage on the client and in the database on the server. Under the hood, Wasp uses the excellent Lucia Auth v3 library for session management.

When users log in, Wasp creates a session for them and stores it in the database. The session is then sent to the client and stored in localStorage. When users log out, Wasp deletes the session from the database and from localStorage.

User Entity​

Password Hashing​

If you are saving a user's password in the database, you should never save it as plain text. You can use Wasp's helper functions for serializing and deserializing provider data which will automatically hash the password for you:

main.wasp
// ...

action updatePassword {
  fn: import { updatePassword } from "@src/auth",
}
src/auth.js
import {
  createProviderId,
  findAuthIdentity,
  updateAuthIdentityProviderData,
  deserializeAndSanitizeProviderData,
} from 'wasp/server/auth';

export const updatePassword = async (args, context) => {
  const providerId = createProviderId('email', args.email)
  const authIdentity = await findAuthIdentity(providerId)
  if (!authIdentity) {
      throw new HttpError(400, "Unknown user")
  }
  
  const providerData = deserializeAndSanitizeProviderData(authIdentity.providerData)

  // Updates the password and hashes it automatically.
  await updateAuthIdentityProviderData(providerId, providerData, {
      hashedPassword: args.password,
  })
}

Default Validations​

When you are using the default authentication flow, Wasp validates the fields with some default validations. These validations run if you use Wasp's built-in Auth UI or if you use the provided auth actions.

If you decide to create your custom auth actions, you'll need to run the validations yourself.

Default validations depend on the auth method you use.

Username & Password​

If you use Username & password authentication, the default validations are:

  • The username must not be empty
  • The password must not be empty, have at least 8 characters, and contain a number

Note that usernames are stored in a case-insensitive manner.

Email​

If you use Email authentication, the default validations are:

  • The email must not be empty and a valid email address
  • The password must not be empty, have at least 8 characters, and contain a number

Note that emails are stored in a case-insensitive manner.

Customizing the Signup Process​

Sometimes you want to include extra fields in your signup process, like first name and last name and save them in the User entity.

For this to happen:

  • you need to define the fields that you want saved in the database,
  • you need to customize the SignupForm (in the case of Email or Username & Password auth)

Other times, you might need to just add some extra UI elements to the form, like a checkbox for terms of service. In this case, customizing only the UI components is enough.

Let's see how to do both.

1. Defining Extra Fields​

If we want to save some extra fields in our signup process, we need to tell our app they exist.

We do that by defining an object where the keys represent the field name, and the values are functions that receive the data sent from the client* and return the value of the field.

* We exclude the password field from this object to prevent it from being saved as plain-text in the database. The password field is handled by Wasp's auth backend.

First, we add the auth.methods.{authMethod}.userSignupFields field in our main.wasp file. The {authMethod} depends on the auth method you are using.

For example, if you are using Username & Password, you would add the auth.methods.usernameAndPassword.userSignupFields field:

main.wasp
app crudTesting {
  // ...
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {
        userSignupFields: import { userSignupFields } from "@src/auth/signup",
      },
    },
    onAuthFailedRedirectTo: "/login",
  },
}

entity User {=psl
  id Int @id @default(autoincrement())
  address String?
psl=}

Then we'll define the userSignupFields object in the src/auth/signup.js file:

src/auth/signup.js
import { defineUserSignupFields } from 'wasp/server/auth'

export const userSignupFields = defineUserSignupFields({
  address: async (data) => {
    const address = data.address
    if (typeof address !== 'string') {
      throw new Error('Address is required')
    }
    if (address.length < 5) {
      throw new Error('Address must be at least 5 characters long')
    }
    return address
  },
})

Read more about the userSignupFields object in the API Reference.

Keep in mind, that these field names need to exist on the userEntity you defined in your main.wasp file e.g. address needs to be a field on the User entity.

The field function will receive the data sent from the client and it needs to return the value that will be saved into the database. If the field is invalid, the function should throw an error.

Using Validation Libraries

You can use any validation library you want to validate the fields. For example, you can use zod like this:

Click to see the code
src/auth/signup.js
import { defineUserSignupFields } from 'wasp/server/auth'
import * as z from 'zod'

export const userSignupFields = defineUserSignupFields({
  address: (data) => {
    const AddressSchema = z
      .string({
        required_error: 'Address is required',
        invalid_type_error: 'Address must be a string',
      })
      .min(10, 'Address must be at least 10 characters long')
    const result = AddressSchema.safeParse(data.address)
    if (result.success === false) {
      throw new Error(result.error.issues[0].message)
    }
    return result.data
  },
})

Now that we defined the fields, Wasp knows how to:

  1. Validate the data sent from the client
  2. Save the data to the database

Next, let's see how to customize Auth UI to include those fields.

2. Customizing the Signup Component​

Using Custom Signup Component

If you are not using Wasp's Auth UI, you can skip this section. Just make sure to include the extra fields in your custom signup form.

Read more about using the signup actions for:

  • email auth here
  • username & password auth here

If you are using Wasp's Auth UI, you can customize the SignupForm component by passing the additionalFields prop to it. It can be either a list of extra fields or a render function.

Using a List of Extra Fields​

When you pass in a list of extra fields to the SignupForm, they are added to the form one by one, in the order you pass them in.

Inside the list, there can be either objects or render functions (you can combine them):

  1. Objects are a simple way to describe new fields you need, but a bit less flexible than render functions.
  2. Render functions can be used to render any UI you want, but they require a bit more code. The render functions receive the react-hook-form object and the form state object as arguments.
src/SignupPage.jsx
import {
  SignupForm,
  FormError,
  FormInput,
  FormItemGroup,
  FormLabel,
} from 'wasp/client/auth'

export const SignupPage = () => {
  return (
    <SignupForm
      additionalFields={[
        /* The address field is defined using an object */
        {
          name: 'address',
          label: 'Address',
          type: 'input',
          validations: {
            required: 'Address is required',
          },
        },
        /* The phone number is defined using a render function */
        (form, state) => {
          return (
            <FormItemGroup>
              <FormLabel>Phone Number</FormLabel>
              <FormInput
                {...form.register('phoneNumber', {
                  required: 'Phone number is required',
                })}
                disabled={state.isLoading}
              />
              {form.formState.errors.phoneNumber && (
                <FormError>
                  {form.formState.errors.phoneNumber.message}
                </FormError>
              )}
            </FormItemGroup>
          )
        },
      ]}
    />
  )
}

Read more about the extra fields in the API Reference.

Using a Single Render Function​

Instead of passing in a list of extra fields, you can pass in a render function which will receive the react-hook-form object and the form state object as arguments. What ever the render function returns, will be rendered below the default fields.

src/SignupPage.jsx
import { SignupForm, FormItemGroup } from 'wasp/client/auth'

export const SignupPage = () => {
  return (
    <SignupForm
      additionalFields={(form, state) => {
        const username = form.watch('username')
        return (
          username && (
            <FormItemGroup>
              Hello there <strong>{username}</strong> 👋
            </FormItemGroup>
          )
        )
      }}
    />
  )
}

Read more about the render function in the API Reference.

API Reference​

Auth Fields​

main.wasp
  title: "My app",
  //...
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {}, // use this or email, not both
      email: {}, // use this or usernameAndPassword, not both
      google: {},
      gitHub: {},
    },
    onAuthFailedRedirectTo: "/someRoute",
    signup: { ... }
  }
}

//...

app.auth is a dictionary with the following fields:

userEntity: entity required​

The entity representing the user connected to your business logic.

You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

methods: dict required​

A dictionary of auth methods enabled for the app.

Email »

Email verification, password reset, etc.

Username & Password »

The simplest way to get started

Google »

Users sign in with their Google account

Github »

Users sign in with their Github account

Keycloak »

Users sign in with their Keycloak account

Click on each auth method for more details.

onAuthFailedRedirectTo: String required​

The route to which Wasp should redirect unauthenticated user when they try to access a private page (i.e., a page that has authRequired: true). Check out these essentials docs on auth to see an example of usage.

onAuthSucceededRedirectTo: String​

The route to which Wasp will send a successfully authenticated after a successful login/signup. The default value is "/".

note

Automatic redirect on successful login only works when using the Wasp-provided Auth UI.

signup: SignupOptions​

Read more about the signup process customization API in the Signup Fields Customization section.

Signup Fields Customization​

If you want to add extra fields to the signup process, the server needs to know how to save them to the database. You do that by defining the auth.methods.{authMethod}.userSignupFields field in your main.wasp file.

main.wasp
app crudTesting {
  // ...
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {
        userSignupFields: import { userSignupFields } from "@src/auth/signup",
      },
    },
    onAuthFailedRedirectTo: "/login",
  },
}

Then we'll export the userSignupFields object from the src/auth/signup.js file:

src/auth/signup.js
import { defineUserSignupFields } from 'wasp/server/auth'

export const userSignupFields = defineUserSignupFields({
  address: async (data) => {
    const address = data.address
    if (typeof address !== 'string') {
      throw new Error('Address is required')
    }
    if (address.length < 5) {
      throw new Error('Address must be at least 5 characters long')
    }
    return address
  },
})

The userSignupFields object is an object where the keys represent the field name, and the values are functions that receive the data sent from the client* and return the value of the field.

If the value that the function received is invalid, the function should throw an error.

* We exclude the password field from this object to prevent it from being saved as plain text in the database. The password field is handled by Wasp's auth backend.

SignupForm Customization​

To customize the SignupForm component, you need to pass in the additionalFields prop. It can be either a list of extra fields or a render function.

src/SignupPage.jsx
import {
  SignupForm,
  FormError,
  FormInput,
  FormItemGroup,
  FormLabel,
} from 'wasp/client/auth'

export const SignupPage = () => {
  return (
    <SignupForm
      additionalFields={[
        {
          name: 'address',
          label: 'Address',
          type: 'input',
          validations: {
            required: 'Address is required',
          },
        },
        (form, state) => {
          return (
            <FormItemGroup>
              <FormLabel>Phone Number</FormLabel>
              <FormInput
                {...form.register('phoneNumber', {
                  required: 'Phone number is required',
                })}
                disabled={state.isLoading}
              />
              {form.formState.errors.phoneNumber && (
                <FormError>
                  {form.formState.errors.phoneNumber.message}
                </FormError>
              )}
            </FormItemGroup>
          )
        },
      ]}
    />
  )
}

The extra fields can be either objects or render functions (you can combine them):

  1. Objects are a simple way to describe new fields you need, but a bit less flexible than render functions.

    The objects have the following properties:

    • name required

      • the name of the field

    • label required

      • the label of the field (used in the UI)

    • type required

      • the type of the field, which can be input or textarea

    • validations

      • an object with the validation rules for the field. The keys are the validation names, and the values are the validation error messages. Read more about the available validation rules in the react-hook-form docs.

  2. Render functions receive the react-hook-form object and the form state as arguments, and they can use them to render arbitrary UI elements.

    The render function has the following signature:

    ;(form: UseFormReturn, state: FormState) => React.ReactNode

    • form required

      • the react-hook-form object, read more about it in the react-hook-form docs
      • you need to use the form.register function to register your fields

    • state required

      • the form state object which has the following properties:
        • isLoading: boolean
          • whether the form is currently submitting
- - + + \ No newline at end of file diff --git a/docs/0.12.0/auth/social-auth/github.html b/docs/0.12.0/auth/social-auth/github.html index 964368161e..002798a067 100644 --- a/docs/0.12.0/auth/social-auth/github.html +++ b/docs/0.12.0/auth/social-auth/github.html @@ -19,16 +19,16 @@ - - + + -
-
Version: 0.12.0

GitHub

Wasp supports Github Authentication out of the box. +

+
Version: 0.12.0

GitHub

Wasp supports Github Authentication out of the box. GitHub is a great external auth choice when you're building apps for developers, as most of them already have a GitHub account.

Letting your users log in using their GitHub accounts turns the signup process into a breeze.

Let's walk through enabling Github Authentication, explain some of the default settings, and show how to override them.

Setting up Github Auth​

Enabling GitHub Authentication comes down to a series of steps:

  1. Enabling GitHub authentication in the Wasp file.
  2. Adding the User entity.
  3. Creating a GitHub OAuth app.
  4. Adding the neccessary Routes and Pages
  5. Using Auth UI components in our Pages.

Here's a skeleton of how our main.wasp should look like after we're done:

main.wasp
// Configuring the social authentication
app myApp {
  auth: { ... }
}

// Defining entities
entity User { ... }

// Defining routes and pages
route LoginRoute { ... }
page LoginPage { ... }

1. Adding Github Auth to Your Wasp File​

Let's start by properly configuring the Auth object:

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    // 1. Specify the User entity  (we'll define it next)
    userEntity: User,
    methods: {
      // 2. Enable Github Auth
      gitHub: {}
    },
    onAuthFailedRedirectTo: "/login"
  },
}

2. Add the User Entity​

Let's now define the app.auth.userEntity entity:

main.wasp
// ...
// 3. Define the User entity
entity User {=psl
    id          Int     @id @default(autoincrement())
    // ...
psl=}

3. Creating a GitHub OAuth App​

To use GitHub as an authentication method, you'll first need to create a GitHub OAuth App and provide Wasp with your client key and secret. Here's how you do it:

  1. Log into your GitHub account and navigate to: https://github.com/settings/developers.
  2. Select New OAuth App.
  3. Supply required information.
GitHub Applications Screenshot
  • For Authorization callback URL:
    • For development, put: http://localhost:3000/auth/login/github.
    • Once you know on which URL your app will be deployed, you can create a new app with that URL instead e.g. https://someotherhost.com/auth/login/github.
  1. Hit Register application.
  2. Hit Generate a new client secret on the next page.
  3. Copy your Client ID and Client secret as you'll need them in the next step.

4. Adding Environment Variables​

Add these environment variables to the .env.server file at the root of your project (take their values from the previous step):

.env.server
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

5. Adding the Necessary Routes and Pages​

Let's define the necessary authentication Routes and Pages.

Add the following code to your main.wasp file:

main.wasp
// ...

// 6. Define the routes
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import { Login } from "@src/pages/auth.jsx"
}

We'll define the React components for these pages in the src/pages/auth.tsx file below.

6. Creating the Client Pages​

info

We are using Tailwind CSS to style the pages. Read more about how to add it here.

Let's create a auth.tsx file in the src/pages folder and add the following to it:

src/pages/auth.jsx
import { LoginForm } from 'wasp/client/auth'

export function Login() {
  return (
    <Layout>
      <LoginForm />
    </Layout>
  )
}

// A layout component to center the content
export function Layout({ children }) {
  return (
    <div className="w-full h-full bg-white">
      <div className="min-w-full min-h-[75vh] flex items-center justify-center">
        <div className="w-full h-full max-w-sm p-5 bg-white">
          <div>{children}</div>
        </div>
      </div>
    </div>
  )
}

We imported the generated Auth UI component and used them in our pages. Read more about the Auth UI components here.

Conclusion​

Yay, we've successfully set up Github Auth! 🎉

Github Auth

Running wasp db migrate-dev and wasp start should now give you a working app with authentication. To see how to protect specific pages (i.e., hide them from non-authenticated users), read the docs on using auth.

Default Behaviour​

Add gitHub: {} to the auth.methods dictionary to use it with default settings.

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      gitHub: {}
    },
    onAuthFailedRedirectTo: "/login"
  },
}

When a user signs in for the first time, Wasp creates a new user account and links it to the chosen auth provider account for future logins.

Overrides​

By default, Wasp doesn't store any information it receives from the social login provider. It only stores the user's ID specific to the provider.

There are two mechanisms used for overriding the default behavior:

  • userSignupFields
  • configFn

Let's explore them in more detail.

Using the User's Provider Account Details​

When a user logs in using a social login provider, the backend receives some data about the user. Wasp lets you access this data inside the userSignupFields getters.

For example, the User entity can include a displayName field which you can set based on the details received from the provider.

Wasp also lets you customize the configuration of the providers' settings using the configFn function.

Let's use this example to show both fields in action:

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      gitHub: {
        configFn: import { getConfig } from "@src/auth/github.js",
        userSignupFields: import { userSignupFields } from "@src/auth/github.js"
      }
    },
    onAuthFailedRedirectTo: "/login"
  },
}

entity User {=psl
    id                        Int     @id @default(autoincrement())
    username                  String  @unique
    displayName               String
psl=}

// ...
src/auth/github.js
export const userSignupFields = {
  username: () => "hardcoded-username",
  displayName: (data) => data.profile.displayName,
};

export function getConfig() {
  return {
    clientID // look up from env or elsewhere
    clientSecret // look up from env or elsewhere
    scope: [],
  };
}

Using Auth​

To read more about how to set up the logout button and get access to the logged-in user in both client and server code, read the docs on using auth.

API Reference​

Provider-specific behavior comes down to implementing two functions.

  • configFn
  • userSignupFields

The reference shows how to define both.

For behavior common to all providers, check the general API Reference.

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      gitHub: {
        configFn: import { getConfig } from "@src/auth/github.js",
        userSignupFields: import { userSignupFields } from "@src/auth/github.js"
      }
    },
    onAuthFailedRedirectTo: "/login"
  },
}

The gitHub dict has the following properties:

  • configFn: ExtImport​

    This function should return an object with the Client ID, Client Secret, and scope for the OAuth provider.

    src/auth/github.js
    export function getConfig() {
      return {
        clientID, // look up from env or elsewhere
        clientSecret, // look up from env or elsewhere
        scope: [],
      }
    }

  • userSignupFields: ExtImport​

    userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

    src/auth.js
    import { defineUserSignupFields } from 'wasp/server/auth'

    export const userSignupFields = defineUserSignupFields({
      address: (data) => {
        if (!data.address) {
          throw new Error('Address is required')
        }
        return data.address
      }
      phone: (data) => data.phone,
    })
    Read more about the `userSignupFields` function [here](../overview#1-defining-extra-fields).
- - + + \ No newline at end of file diff --git a/docs/0.12.0/auth/social-auth/google.html b/docs/0.12.0/auth/social-auth/google.html index a6e6ff0580..2ae5cb7584 100644 --- a/docs/0.12.0/auth/social-auth/google.html +++ b/docs/0.12.0/auth/social-auth/google.html @@ -19,17 +19,17 @@ - - + + -
-
Version: 0.12.0

Google

Wasp supports Google Authentication out of the box. +

+
Version: 0.12.0

Google

Wasp supports Google Authentication out of the box. Google Auth is arguably the best external auth option, as most users on the web already have Google accounts.

Enabling it lets your users log in using their existing Google accounts, greatly simplifying the process and enhancing the user experience.

Let's walk through enabling Google authentication, explain some of the default settings, and show how to override them.

Setting up Google Auth​

Enabling Google Authentication comes down to a series of steps:

  1. Enabling Google authentication in the Wasp file.
  2. Adding the User entity.
  3. Creating a Google OAuth app.
  4. Adding the neccessary Routes and Pages
  5. Using Auth UI components in our Pages.

Here's a skeleton of how our main.wasp should look like after we're done:

main.wasp
// Configuring the social authentication
app myApp {
  auth: { ... }
}

// Defining entities
entity User { ... }

// Defining routes and pages
route LoginRoute { ... }
page LoginPage { ... }

1. Adding Google Auth to Your Wasp File​

Let's start by properly configuring the Auth object:

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    // 1. Specify the User entity (we'll define it next)
    userEntity: User,
    methods: {
      // 2. Enable Google Auth
      google: {}
    },
    onAuthFailedRedirectTo: "/login"
  },
}

userEntity is explained in the social auth overview.

2. Adding the User Entity​

Let's now define the app.auth.userEntity entity:

main.wasp
// ...
// 3. Define the User entity
entity User {=psl
    id          Int     @id @default(autoincrement())
    // ...
psl=}

3. Creating a Google OAuth App​

To use Google as an authentication method, you'll first need to create a Google project and provide Wasp with your client key and secret. Here's how you do it:

  1. Create a Google Cloud Platform account if you do not already have one: https://cloud.google.com/
  2. Create and configure a new Google project here: https://console.cloud.google.com/home/dashboard

Google Console Screenshot 1

Google Console Screenshot 2

  1. Search for OAuth in the top bar, click on OAuth consent screen.

Google Console Screenshot 3

  • Select what type of app you want, we will go with External.

    Google Console Screenshot 4

  • Fill out applicable information on Page 1.

    Google Console Screenshot 5

  • On Page 2, Scopes, you should select userinfo.profile. You can optionally search for other things, like email.

    Google Console Screenshot 6

    Google Console Screenshot 7

    Google Console Screenshot 8

  • Add any test users you want on Page 3.

    Google Console Screenshot 9

  1. Next, click Credentials.

Google Console Screenshot 10

  • Select Create Credentials.

  • Select OAuth client ID.

    Google Console Screenshot 11

  • Complete the form

    Google Console Screenshot 12

  • Under Authorized redirect URIs, put in: http://localhost:3000/auth/login/google

    Google Console Screenshot 13

    • Once you know on which URL(s) your API server will be deployed, also add those URL(s).
      • For example: https://someotherhost.com/auth/login/google

  • When you save, you can click the Edit icon and your credentials will be shown.

    Google Console Screenshot 14

  1. Copy your Client ID and Client secret as you will need them in the next step.

4. Adding Environment Variables​

Add these environment variables to the .env.server file at the root of your project (take their values from the previous step):

.env.server
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

5. Adding the Necessary Routes and Pages​

Let's define the necessary authentication Routes and Pages.

Add the following code to your main.wasp file:

main.wasp
// ...

// 6. Define the routes
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import { Login } from "@src/pages/auth.jsx"
}

We'll define the React components for these pages in the src/pages/auth.tsx file below.

6. Create the Client Pages​

info

We are using Tailwind CSS to style the pages. Read more about how to add it here.

Let's now create a auth.tsx file in the src/pages. It should have the following code:

src/pages/auth.jsx
import { LoginForm } from 'wasp/client/auth'

export function Login() {
  return (
    <Layout>
      <LoginForm />
    </Layout>
  )
}

// A layout component to center the content
export function Layout({ children }) {
  return (
    <div className="w-full h-full bg-white">
      <div className="min-w-full min-h-[75vh] flex items-center justify-center">
        <div className="w-full h-full max-w-sm p-5 bg-white">
          <div>{children}</div>
        </div>
      </div>
    </div>
  )
}
Auth UI

Our pages use an automatically-generated Auth UI component. Read more about Auth UI components here.

Conclusion​

Yay, we've successfully set up Google Auth! 🎉

Google Auth

Running wasp db migrate-dev and wasp start should now give you a working app with authentication. To see how to protect specific pages (i.e., hide them from non-authenticated users), read the docs on using auth.

Default Behaviour​

Add google: {} to the auth.methods dictionary to use it with default settings:

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      google: {}
    },
    onAuthFailedRedirectTo: "/login"
  },
}

When a user signs in for the first time, Wasp creates a new user account and links it to the chosen auth provider account for future logins.

Overrides​

By default, Wasp doesn't store any information it receives from the social login provider. It only stores the user's ID specific to the provider.

There are two mechanisms used for overriding the default behavior:

  • userSignupFields
  • configFn

Let's explore them in more detail.

Using the User's Provider Account Details​

When a user logs in using a social login provider, the backend receives some data about the user. Wasp lets you access this data inside the userSignupFields getters.

For example, the User entity can include a displayName field which you can set based on the details received from the provider.

Wasp also lets you customize the configuration of the providers' settings using the configFn function.

Let's use this example to show both fields in action:

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      google: {
        configFn: import { getConfig } from "@src/auth/google.js",
        userSignupFields: import { userSignupFields } from "@src/auth/google.js"
      }
    },
    onAuthFailedRedirectTo: "/login"
  },
}

entity User {=psl
    id                        Int     @id @default(autoincrement())
    username                  String  @unique
    displayName               String
psl=}

// ...
src/auth/google.js
export const userSignupFields = {
  username: () => "hardcoded-username",
  displayName: (data) => data.profile.displayName,
}

export function getConfig() {
  return {
    clientID, // look up from env or elsewhere
    clientSecret, // look up from env or elsewhere
    scope: ['profile', 'email'],
  }
}

Using Auth​

To read more about how to set up the logout button and get access to the logged-in user in both client and server code, read the docs on using auth.

API Reference​

Provider-specific behavior comes down to implementing two functions.

  • configFn
  • userSignupFields

The reference shows how to define both.

For behavior common to all providers, check the general API Reference.

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      google: {
        configFn: import { getConfig } from "@src/auth/google.js",
        userSignupFields: import { userSignupFields } from "@src/auth/google.js"
      }
    },
    onAuthFailedRedirectTo: "/login"
  },
}

The google dict has the following properties:

  • configFn: ExtImport​

    This function must return an object with the Client ID, the Client Secret, and the scope for the OAuth provider.

    src/auth/google.js
    export function getConfig() {
      return {
        clientID, // look up from env or elsewhere
        clientSecret, // look up from env or elsewhere
        scope: ['profile', 'email'],
      }
    }

  • userSignupFields: ExtImport​

    userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

    src/auth.js
    import { defineUserSignupFields } from 'wasp/server/auth'

    export const userSignupFields = defineUserSignupFields({
      address: (data) => {
        if (!data.address) {
          throw new Error('Address is required')
        }
        return data.address
      }
      phone: (data) => data.phone,
    })
    Read more about the `userSignupFields` function [here](../overview#1-defining-extra-fields).
- - + + \ No newline at end of file diff --git a/docs/0.12.0/auth/social-auth/overview.html b/docs/0.12.0/auth/social-auth/overview.html index 3aa94d60db..d0b54c7044 100644 --- a/docs/0.12.0/auth/social-auth/overview.html +++ b/docs/0.12.0/auth/social-auth/overview.html @@ -19,19 +19,19 @@ - - + + -
-
Version: 0.12.0

Overview

Social login options (e.g., Log in with Google) are a great (maybe even the best) solution for handling user accounts. +

+
Version: 0.12.0

Overview

Social login options (e.g., Log in with Google) are a great (maybe even the best) solution for handling user accounts. A famous old developer joke tells us "The best auth system is the one you never have to make."

Wasp wants to make adding social login options to your app as painless as possible.

Using different social providers gives users a chance to sign into your app via their existing accounts on other platforms (Google, GitHub, etc.).

This page goes through the common behaviors between all supported social login providers and shows you how to customize them. It also gives an overview of Wasp's UI helpers - the quickest possible way to get started with social auth.

Available Providers​

Wasp currently supports the following social login providers:

User Entity​

Wasp requires you to declare a userEntity for all auth methods (social or otherwise). This field tells Wasp which Entity represents the user.

Here's what the full setup looks like:

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      google: {}
    },
    onAuthFailedRedirectTo: "/login"
  },
}

entity User {=psl
    id                        Int           @id @default(autoincrement())
    //...
psl=}

To learn more about what the fields on these entities represent, look at the API Reference.

Default Behavior​

When a user signs in for the first time, Wasp creates a new user account and links it to the chosen auth provider account for future logins.

Overrides​

By default, Wasp doesn't store any information it receives from the social login provider. It only stores the user's ID specific to the provider.

If you wish to store more information about the user, you can override the default behavior. You can do this by defining the userSignupFields and configFn fields in main.wasp for each provider.

You can create custom signup setups, such as allowing users to define a custom username after they sign up with a social provider.

Example: Allowing User to Set Their Username​

If you want to modify the signup flow (e.g., let users choose their own usernames), you will need to go through three steps:

  1. The first step is adding a isSignupComplete property to your User Entity. This field will signal whether the user has completed the signup process.
  2. The second step is overriding the default signup behavior.
  3. The third step is implementing the rest of your signup flow and redirecting users where appropriate.

Let's go through both steps in more detail.

1. Adding the isSignupComplete Field to the User Entity​

main.wasp
entity User {=psl
    id                        Int           @id @default(autoincrement())
    username                  String?       @unique
    isSignupComplete          Boolean       @default(false)
psl=}

2. Overriding the Default Behavior​

Declare an import under app.auth.methods.google.userSignupFields (the example assumes you're using Google):

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      google: {
        userSignupFields: import { userSignupFields } from "@src/auth/google.js"
      }
    },
    onAuthFailedRedirectTo: "/login"
  },
}

// ...

And implement the imported function.

src/auth/google.js
export const userSignupFields = {
  isSignupComplete: () => false,
}

3. Showing the Correct State on the Client​

You can query the user's isSignupComplete flag on the client with the useAuth() hook. Depending on the flag's value, you can redirect users to the appropriate signup step.

For example:

  1. When the user lands on the homepage, check the value of user.isSignupComplete.
  2. If it's false, it means the user has started the signup process but hasn't yet chosen their username. Therefore, you can redirect them to EditUserDetailsPage where they can edit the username property.
src/HomePage.jsx
import { useAuth } from 'wasp/client/auth'
import { Redirect } from 'react-router-dom'

export function HomePage() {
  const { data: user } = useAuth()

  if (user.isSignupComplete === false) {
    return <Redirect to="/edit-user-details" />
  }

  // ...
}

Using the User's Provider Account Details​

Account details are provider-specific. Each provider has their own rules for defining the userSignupFields and configFn fields:

UI Helpers​

Use Auth UI

Auth UI is a common name for all high-level auth forms that come with Wasp.

These include fully functional auto-generated login and signup forms with working social login buttons. If you're looking for the fastest way to get your auth up and running, that's where you should look.

The UI helpers described below are lower-level and are useful for creating your custom forms.

Wasp provides sign-in buttons and URLs for each of the supported social login providers.

src/LoginPage.jsx
import {
  GoogleSignInButton,
  googleSignInUrl,
  GitHubSignInButton,
  gitHubSignInUrl,
} from 'wasp/client/auth'

export const LoginPage = () => {
  return (
    <>
      <GoogleSignInButton />
      <GitHubSignInButton />
      {/* or */}
      <a href={googleSignInUrl}>Sign in with Google</a>
      <a href={gitHubSignInUrl}>Sign in with GitHub</a>
    </>
  )
}

If you need even more customization, you can create your custom components using signInUrls.

API Reference​

Fields in the app.auth Dictionary and Overrides​

For more information on:

  • Allowed fields in app.auth
  • userSignupFields and configFn functions

Check the provider-specific API References:

- - + + \ No newline at end of file diff --git a/docs/0.12.0/auth/ui.html b/docs/0.12.0/auth/ui.html index 3244b34ad7..41868d20ee 100644 --- a/docs/0.12.0/auth/ui.html +++ b/docs/0.12.0/auth/ui.html @@ -19,13 +19,13 @@ - - + + -
-
Version: 0.12.0

Auth UI

To make using authentication in your app as easy as possible, Wasp generates the server-side code but also the client-side UI for you. It enables you to quickly get the login, signup, password reset and email verification flows in your app.

Below we cover all of the available UI components and how to use them.

Auth UI

Overview​

After Wasp generates the UI components for your auth, you can use it as is, or customize it to your liking.

Based on the authentication providers you enabled in your main.wasp file, the Auth UI will show the corresponding UI (form and buttons). For example, if you enabled e-mail authentication:

main.wasp
app MyApp {
  //...
  auth: {
    methods: {
      email: {},
    },
    // ...
  }
}

You'll get the following UI:

Auth UI

And then if you enable Google and Github:

main.wasp
app MyApp {
  //...
  auth: {
    methods: {
      email: {},
      google: {},
      github: {},
    },
    // ...
  }
}

The form will automatically update to look like this:

Auth UI

Let's go through all of the available components and how to use them.

Auth Components​

The following components are available for you to use in your app:

Login Form​

Used with Username & Password, Email, Github and Google authentication.

Login form

You can use the LoginForm component to build your login page:

main.wasp
// ...

route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import { LoginPage } from "@src/LoginPage.jsx"
}
src/LoginPage.jsx
import { LoginForm } from 'wasp/client/auth'

// Use it like this
export function LoginPage() {
  return <LoginForm />
}

It will automatically show the correct authentication providers based on your main.wasp file.

Signup Form​

Used with Username & Password, Email, Github and Google authentication.

Signup form

You can use the SignupForm component to build your signup page:

main.wasp
// ...

route SignupRoute { path: "/signup", to: SignupPage }
page SignupPage {
  component: import { SignupPage } from "@src/SignupPage.jsx"
}
src/SignupPage.jsx
import { SignupForm } from 'wasp/client/auth'

// Use it like this
export function SignupPage() {
  return <SignupForm />
}

It will automatically show the correct authentication providers based on your main.wasp file.

Read more about customizing the signup process like adding additional fields or extra UI in the Auth Overview section.

Forgot Password Form​

Used with Email authentication.

If users forget their password, they can use this form to reset it.

Forgot password form

You can use the ForgotPasswordForm component to build your own forgot password page:

main.wasp
// ...

route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
page RequestPasswordResetPage {
  component: import { ForgotPasswordPage } from "@src/ForgotPasswordPage.jsx"
}
src/ForgotPasswordPage.jsx
import { ForgotPasswordForm } from 'wasp/client/auth'

// Use it like this
export function ForgotPasswordPage() {
  return <ForgotPasswordForm />
}

Reset Password Form​

Used with Email authentication.

After users click on the link in the email they receive after submitting the forgot password form, they will be redirected to this form where they can reset their password.

Reset password form

You can use the ResetPasswordForm component to build your reset password page:

main.wasp
// ...

route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
page PasswordResetPage {
  component: import { ResetPasswordPage } from "@src/ResetPasswordPage.jsx"
}
src/ResetPasswordPage.jsx
import { ResetPasswordForm } from 'wasp/client/auth'

// Use it like this
export function ResetPasswordPage() {
  return <ResetPasswordForm />
}

Verify Email Form​

Used with Email authentication.

After users sign up, they will receive an email with a link to this form where they can verify their email.

Verify email form

You can use the VerifyEmailForm component to build your email verification page:

main.wasp
// ...

route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
page EmailVerificationPage {
  component: import { VerifyEmailPage } from "@src/VerifyEmailPage.jsx"
}
src/VerifyEmailPage.jsx
import { VerifyEmailForm } from 'wasp/client/auth'

// Use it like this
export function VerifyEmailPage() {
  return <VerifyEmailForm />
}

Customization 💅🏻​

You customize all of the available forms by passing props to them.

Props you can pass to all of the forms:

  1. appearance - customize the form colors (via design tokens)
  2. logo - path to your logo
  3. socialLayout - layout of the social buttons, which can be vertical or horizontal

1. Customizing the Colors​

We use Stitches to style the Auth UI. You can customize the styles by overriding the default theme tokens.

List of all available tokens

See the list of all available tokens which you can override.

src/appearance.js
export const authAppearance = {
  colors: {
    brand: '#5969b8', // blue
    brandAccent: '#de5998', // pink
    submitButtonText: 'white',
  },
}
src/LoginPage.jsx
import { LoginForm } from 'wasp/client/auth'
import { authAppearance } from './appearance'

export function LoginPage() {
  return (
    <LoginForm
      // Pass the appearance object to the form
      appearance={authAppearance}
    />
  )
}

We recommend defining your appearance in a separate file and importing it into your components.

You can add your logo to the Auth UI by passing the logo prop to any of the components.

src/LoginPage.jsx
import { LoginForm } from 'wasp/client/auth'
import Logo from './logo.png'

export function LoginPage() {
  return (
    <LoginForm
      // Pass in the path to your logo
      logo={Logo}
    />
  )
}

3. Social Buttons Layout​

You can change the layout of the social buttons by passing the socialLayout prop to any of the components. It can be either vertical or horizontal (default).

If we pass in vertical:

src/LoginPage.jsx
import { LoginForm } from 'wasp/client/auth'

export function LoginPage() {
  return (
    <LoginForm
      // Pass in the socialLayout prop
      socialLayout="vertical"
    />
  )
}

We get this:

Vertical social buttons

Let's Put Everything Together 🪄​

If we provide the logo and custom colors:

src/appearance.js
export const appearance = {
  colors: {
    brand: '#5969b8', // blue
    brandAccent: '#de5998', // pink
    submitButtonText: 'white',
  },
}
src/LoginPage.jsx
import { LoginForm } from 'wasp/client/auth'

import { authAppearance } from './appearance'
import todoLogo from './todoLogo.png'

export function LoginPage() {
  return <LoginForm appearance={appearance} logo={todoLogo} />
}

We get a form looking like this:

Custom login form
- - +
+
Version: 0.12.0

Auth UI

To make using authentication in your app as easy as possible, Wasp generates the server-side code but also the client-side UI for you. It enables you to quickly get the login, signup, password reset and email verification flows in your app.

Below we cover all of the available UI components and how to use them.

Auth UI

Overview​

After Wasp generates the UI components for your auth, you can use it as is, or customize it to your liking.

Based on the authentication providers you enabled in your main.wasp file, the Auth UI will show the corresponding UI (form and buttons). For example, if you enabled e-mail authentication:

main.wasp
app MyApp {
  //...
  auth: {
    methods: {
      email: {},
    },
    // ...
  }
}

You'll get the following UI:

Auth UI

And then if you enable Google and Github:

main.wasp
app MyApp {
  //...
  auth: {
    methods: {
      email: {},
      google: {},
      github: {},
    },
    // ...
  }
}

The form will automatically update to look like this:

Auth UI

Let's go through all of the available components and how to use them.

Auth Components​

The following components are available for you to use in your app:

Login Form​

Used with Username & Password, Email, Github and Google authentication.

Login form

You can use the LoginForm component to build your login page:

main.wasp
// ...

route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import { LoginPage } from "@src/LoginPage.jsx"
}
src/LoginPage.jsx
import { LoginForm } from 'wasp/client/auth'

// Use it like this
export function LoginPage() {
  return <LoginForm />
}

It will automatically show the correct authentication providers based on your main.wasp file.

Signup Form​

Used with Username & Password, Email, Github and Google authentication.

Signup form

You can use the SignupForm component to build your signup page:

main.wasp
// ...

route SignupRoute { path: "/signup", to: SignupPage }
page SignupPage {
  component: import { SignupPage } from "@src/SignupPage.jsx"
}
src/SignupPage.jsx
import { SignupForm } from 'wasp/client/auth'

// Use it like this
export function SignupPage() {
  return <SignupForm />
}

It will automatically show the correct authentication providers based on your main.wasp file.

Read more about customizing the signup process like adding additional fields or extra UI in the Auth Overview section.

Forgot Password Form​

Used with Email authentication.

If users forget their password, they can use this form to reset it.

Forgot password form

You can use the ForgotPasswordForm component to build your own forgot password page:

main.wasp
// ...

route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
page RequestPasswordResetPage {
  component: import { ForgotPasswordPage } from "@src/ForgotPasswordPage.jsx"
}
src/ForgotPasswordPage.jsx
import { ForgotPasswordForm } from 'wasp/client/auth'

// Use it like this
export function ForgotPasswordPage() {
  return <ForgotPasswordForm />
}

Reset Password Form​

Used with Email authentication.

After users click on the link in the email they receive after submitting the forgot password form, they will be redirected to this form where they can reset their password.

Reset password form

You can use the ResetPasswordForm component to build your reset password page:

main.wasp
// ...

route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
page PasswordResetPage {
  component: import { ResetPasswordPage } from "@src/ResetPasswordPage.jsx"
}
src/ResetPasswordPage.jsx
import { ResetPasswordForm } from 'wasp/client/auth'

// Use it like this
export function ResetPasswordPage() {
  return <ResetPasswordForm />
}

Verify Email Form​

Used with Email authentication.

After users sign up, they will receive an email with a link to this form where they can verify their email.

Verify email form

You can use the VerifyEmailForm component to build your email verification page:

main.wasp
// ...

route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
page EmailVerificationPage {
  component: import { VerifyEmailPage } from "@src/VerifyEmailPage.jsx"
}
src/VerifyEmailPage.jsx
import { VerifyEmailForm } from 'wasp/client/auth'

// Use it like this
export function VerifyEmailPage() {
  return <VerifyEmailForm />
}

Customization 💅🏻​

You customize all of the available forms by passing props to them.

Props you can pass to all of the forms:

  1. appearance - customize the form colors (via design tokens)
  2. logo - path to your logo
  3. socialLayout - layout of the social buttons, which can be vertical or horizontal

1. Customizing the Colors​

We use Stitches to style the Auth UI. You can customize the styles by overriding the default theme tokens.

List of all available tokens

See the list of all available tokens which you can override.

src/appearance.js
export const authAppearance = {
  colors: {
    brand: '#5969b8', // blue
    brandAccent: '#de5998', // pink
    submitButtonText: 'white',
  },
}
src/LoginPage.jsx
import { LoginForm } from 'wasp/client/auth'
import { authAppearance } from './appearance'

export function LoginPage() {
  return (
    <LoginForm
      // Pass the appearance object to the form
      appearance={authAppearance}
    />
  )
}

We recommend defining your appearance in a separate file and importing it into your components.

You can add your logo to the Auth UI by passing the logo prop to any of the components.

src/LoginPage.jsx
import { LoginForm } from 'wasp/client/auth'
import Logo from './logo.png'

export function LoginPage() {
  return (
    <LoginForm
      // Pass in the path to your logo
      logo={Logo}
    />
  )
}

3. Social Buttons Layout​

You can change the layout of the social buttons by passing the socialLayout prop to any of the components. It can be either vertical or horizontal (default).

If we pass in vertical:

src/LoginPage.jsx
import { LoginForm } from 'wasp/client/auth'

export function LoginPage() {
  return (
    <LoginForm
      // Pass in the socialLayout prop
      socialLayout="vertical"
    />
  )
}

We get this:

Vertical social buttons

Let's Put Everything Together 🪄​

If we provide the logo and custom colors:

src/appearance.js
export const appearance = {
  colors: {
    brand: '#5969b8', // blue
    brandAccent: '#de5998', // pink
    submitButtonText: 'white',
  },
}
src/LoginPage.jsx
import { LoginForm } from 'wasp/client/auth'

import { authAppearance } from './appearance'
import todoLogo from './todoLogo.png'

export function LoginPage() {
  return <LoginForm appearance={appearance} logo={todoLogo} />
}

We get a form looking like this:

Custom login form
+ + \ No newline at end of file diff --git a/docs/0.12.0/auth/username-and-pass.html b/docs/0.12.0/auth/username-and-pass.html index 71fcac7ca0..aac306ec5a 100644 --- a/docs/0.12.0/auth/username-and-pass.html +++ b/docs/0.12.0/auth/username-and-pass.html @@ -19,13 +19,13 @@ - - + + -
-
Version: 0.12.0

Username & Password

Wasp supports username & password authentication out of the box with login and signup flows. It provides you with the server-side implementation and the UI components for the client-side.

Setting Up Username & Password Authentication​

To set up username authentication we need to:

  1. Enable username authentication in the Wasp file
  2. Add the User entity
  3. Add the auth routes and pages
  4. Use Auth UI components in our pages

Structure of the main.wasp file we will end up with:

main.wasp
// Configuring e-mail authentication
app myApp {
  auth: { ... }
}
// Defining User entity
entity User { ... }
// Defining routes and pages
route SignupRoute { ... }
page SignupPage { ... }
// ...

1. Enable Username Authentication​

Let's start with adding the following to our main.wasp file:

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    // 1. Specify the user entity (we'll define it next)
    userEntity: User,
    methods: {
      // 2. Enable username authentication
      usernameAndPassword: {},
    },
    onAuthFailedRedirectTo: "/login"
  }
}

Read more about the usernameAndPassword auth method options here.

2. Add the User Entity​

The User entity can be as simple as including only the id field:

main.wasp
// 3. Define the user entity
entity User {=psl
    id                        Int           @id @default(autoincrement())
    // Add your own fields below
    // ...
psl=}

You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

3. Add the Routes and Pages​

Next, we need to define the routes and pages for the authentication pages.

Add the following to the main.wasp file:

main.wasp
// ...
// 4. Define the routes
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import { Login } from "@src/pages/auth.jsx"
}
route SignupRoute { path: "/signup", to: SignupPage }
page SignupPage {
  component: import { Signup } from "@src/pages/auth.jsx"
}

We'll define the React components for these pages in the src/pages/auth.tsx file below.

4. Create the Client Pages​

info

We are using Tailwind CSS to style the pages. Read more about how to add it here.

Let's create a auth.tsx file in the src/pages folder and add the following to it:

src/pages/auth.jsx
import { LoginForm, SignupForm } from 'wasp/client/auth'
import { Link } from 'react-router-dom'

export function Login() {
  return (
    <Layout>
      <LoginForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        Don't have an account yet? <Link to="/signup">go to signup</Link>.
      </span>
    </Layout>
  );
}

export function Signup() {
  return (
    <Layout>
      <SignupForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        I already have an account (<Link to="/login">go to login</Link>).
      </span>
    </Layout>
  );
}

// A layout component to center the content
export function Layout({ children }) {
  return (
    <div className="w-full h-full bg-white">
      <div className="min-w-full min-h-[75vh] flex items-center justify-center">
        <div className="w-full h-full max-w-sm p-5 bg-white">
          <div>{children}</div>
        </div>
      </div>
    </div>
  );
}

We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

Conclusion​

That's it! We have set up username authentication in our app. 🎉

Running wasp db migrate-dev and then wasp start should give you a working app with username authentication. If you want to put some of the pages behind authentication, read the auth overview docs.

Using multiple auth identities for a single user

Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

Customizing the Auth Flow​

The login and signup flows are pretty standard: they allow the user to sign up and then log in with their username and password. The signup flow validates the username and password and then creates a new user entity in the database.

Read more about the default username and password validation rules in the auth overview docs.

If you require more control in your authentication flow, you can achieve that in the following ways:

  1. Create your UI and use signup and login actions.
  2. Create your custom sign-up action which uses the lower-level API, along with your custom code.

1. Using the signup and login actions​

login()​

An action for logging in the user.

It takes two arguments:

  • username: string required

    Username of the user logging in.

  • password: string required

    Password of the user logging in.

You can use it like this:

src/pages/auth.jsx
import { login } from 'wasp/client/auth'

import { useState } from 'react'
import { useHistory, Link } from 'react-router-dom'

export function LoginPage() {
  const [username, setUsername] = useState('')
  const [password, setPassword] = useState('')
  const [error, setError] = useState(null)
  const history = useHistory()

  async function handleSubmit(event) {
    event.preventDefault()
    try {
      await login(username, password)
      history.push('/')
    } catch (error) {
      setError(error)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* ... */}
    </form>
  );
}
note

When using the exposed login() function, make sure to implement your redirect on success login logic (e.g. redirecting to home).

signup()​

An action for signing up the user. This action does not log in the user, you still need to call login().

It takes one argument:

  • userFields: object required

    It has the following fields:

    • username: string required

    • password: string required

    info

    By default, Wasp will only save the username and password fields. If you want to add extra fields to your signup process, read about defining extra signup fields.

You can use it like this:

src/pages/auth.jsx
import { signup, login } from 'wasp/client/auth'

import { useState } from 'react'
import { useHistory } from 'react-router-dom'
import { Link } from 'react-router-dom'

export function Signup() {
  const [username, setUsername] = useState('')
  const [password, setPassword] = useState('')
  const [error, setError] = useState(null)
  const history = useHistory()

  async function handleSubmit(event) {
    event.preventDefault()
    try {
      await signup({
        username,
        password,
      })
      await login(username, password)
      history.push("/")
    } catch (error) {
      setError(error)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* ... */}
    </form>
  );
}

2. Creating your custom sign-up action​

The code of your custom sign-up action can look like this:

main.wasp
// ...

action customSignup {
  fn: import { signup } from "@src/auth/signup.js",
}
src/auth/signup.js
import {
  ensurePasswordIsPresent,
  ensureValidPassword,
  ensureValidUsername,
  createProviderId,
  sanitizeAndSerializeProviderData,
  createUser,
} from 'wasp/server/auth'

export const signup = async (args, _context) => {
  ensureValidUsername(args)
  ensurePasswordIsPresent(args)
  ensureValidPassword(args)

  try {
    const providerId = createProviderId('username', args.username)
    const providerData = await sanitizeAndSerializeProviderData({
      hashedPassword: args.password,
    })

    await createUser(
      providerId,
      providerData,
      // Any additional data you want to store on the User entity
      {},
    )
  } catch (e) {
    return {
      success: false,
      message: e.message,
    }
  }

  // Your custom code after sign-up.
  // ...

  return {
    success: true,
    message: 'User created successfully',
  }
}

We suggest using the built-in field validators for your authentication flow. You can import them from wasp/server/auth. These are the same validators that Wasp uses internally for the default authentication flow.

Username​

  • ensureValidUsername(args)

    Checks if the username is valid and throws an error if it's not. Read more about the validation rules here.

Password​

  • ensurePasswordIsPresent(args)

    Checks if the password is present and throws an error if it's not.

  • ensureValidPassword(args)

    Checks if the password is valid and throws an error if it's not. Read more about the validation rules here.

Using Auth​

To read more about how to set up the logout button and how to get access to the logged-in user in our client and server code, read the auth overview docs.

getUsername​

If you are looking to access the user's username in your code, you can do that by accessing the info about the user that is stored in the user.auth.identities array.

To make things a bit easier for you, Wasp offers the getUsername helper.

The getUsername helper returns the user's username or null if the user doesn't have a username auth identity.

src/MainPage.jsx
import { getUsername } from 'wasp/auth'

const MainPage = ({ user }) => {
  const username = getUsername(user)
  // ...
}
src/tasks.js
import { getUsername } from 'wasp/auth'

export const createTask = async (args, context) => {
  const username = getUsername(context.user)
  // ...
}

API Reference​

userEntity fields​

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {},
    },
    onAuthFailedRedirectTo: "/login"
  }
}

entity User {=psl
    id                        Int           @id @default(autoincrement())
psl=}

The user entity needs to have the following fields:

  • id required

    It can be of any type, but it needs to be marked with @id

You can add any other fields you want to the user entity. Make sure to also define them in the userSignupFields field if they need to be set during the sign-up process.

Fields in the usernameAndPassword dict​

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {
        userSignupFields: import { userSignupFields } from "@src/auth/email.js",
      },
    },
    onAuthFailedRedirectTo: "/login"
  }
}
// ...

userSignupFields: ExtImport​

userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

src/auth.js
import { defineUserSignupFields } from 'wasp/server/auth'

export const userSignupFields = defineUserSignupFields({
  address: (data) => {
    if (!data.address) {
      throw new Error('Address is required')
    }
    return data.address
  }
  phone: (data) => data.phone,
})
Read more about the `userSignupFields` function [here](./overview#1-defining-extra-fields).
- - +
+
Version: 0.12.0

Username & Password

Wasp supports username & password authentication out of the box with login and signup flows. It provides you with the server-side implementation and the UI components for the client-side.

Setting Up Username & Password Authentication​

To set up username authentication we need to:

  1. Enable username authentication in the Wasp file
  2. Add the User entity
  3. Add the auth routes and pages
  4. Use Auth UI components in our pages

Structure of the main.wasp file we will end up with:

main.wasp
// Configuring e-mail authentication
app myApp {
  auth: { ... }
}
// Defining User entity
entity User { ... }
// Defining routes and pages
route SignupRoute { ... }
page SignupPage { ... }
// ...

1. Enable Username Authentication​

Let's start with adding the following to our main.wasp file:

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    // 1. Specify the user entity (we'll define it next)
    userEntity: User,
    methods: {
      // 2. Enable username authentication
      usernameAndPassword: {},
    },
    onAuthFailedRedirectTo: "/login"
  }
}

Read more about the usernameAndPassword auth method options here.

2. Add the User Entity​

The User entity can be as simple as including only the id field:

main.wasp
// 3. Define the user entity
entity User {=psl
    id                        Int           @id @default(autoincrement())
    // Add your own fields below
    // ...
psl=}

You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

3. Add the Routes and Pages​

Next, we need to define the routes and pages for the authentication pages.

Add the following to the main.wasp file:

main.wasp
// ...
// 4. Define the routes
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import { Login } from "@src/pages/auth.jsx"
}
route SignupRoute { path: "/signup", to: SignupPage }
page SignupPage {
  component: import { Signup } from "@src/pages/auth.jsx"
}

We'll define the React components for these pages in the src/pages/auth.tsx file below.

4. Create the Client Pages​

info

We are using Tailwind CSS to style the pages. Read more about how to add it here.

Let's create a auth.tsx file in the src/pages folder and add the following to it:

src/pages/auth.jsx
import { LoginForm, SignupForm } from 'wasp/client/auth'
import { Link } from 'react-router-dom'

export function Login() {
  return (
    <Layout>
      <LoginForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        Don't have an account yet? <Link to="/signup">go to signup</Link>.
      </span>
    </Layout>
  );
}

export function Signup() {
  return (
    <Layout>
      <SignupForm />
      <br />
      <span className="text-sm font-medium text-gray-900">
        I already have an account (<Link to="/login">go to login</Link>).
      </span>
    </Layout>
  );
}

// A layout component to center the content
export function Layout({ children }) {
  return (
    <div className="w-full h-full bg-white">
      <div className="min-w-full min-h-[75vh] flex items-center justify-center">
        <div className="w-full h-full max-w-sm p-5 bg-white">
          <div>{children}</div>
        </div>
      </div>
    </div>
  );
}

We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

Conclusion​

That's it! We have set up username authentication in our app. 🎉

Running wasp db migrate-dev and then wasp start should give you a working app with username authentication. If you want to put some of the pages behind authentication, read the auth overview docs.

Using multiple auth identities for a single user

Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

Customizing the Auth Flow​

The login and signup flows are pretty standard: they allow the user to sign up and then log in with their username and password. The signup flow validates the username and password and then creates a new user entity in the database.

Read more about the default username and password validation rules in the auth overview docs.

If you require more control in your authentication flow, you can achieve that in the following ways:

  1. Create your UI and use signup and login actions.
  2. Create your custom sign-up action which uses the lower-level API, along with your custom code.

1. Using the signup and login actions​

login()​

An action for logging in the user.

It takes two arguments:

  • username: string required

    Username of the user logging in.

  • password: string required

    Password of the user logging in.

You can use it like this:

src/pages/auth.jsx
import { login } from 'wasp/client/auth'

import { useState } from 'react'
import { useHistory, Link } from 'react-router-dom'

export function LoginPage() {
  const [username, setUsername] = useState('')
  const [password, setPassword] = useState('')
  const [error, setError] = useState(null)
  const history = useHistory()

  async function handleSubmit(event) {
    event.preventDefault()
    try {
      await login(username, password)
      history.push('/')
    } catch (error) {
      setError(error)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* ... */}
    </form>
  );
}
note

When using the exposed login() function, make sure to implement your redirect on success login logic (e.g. redirecting to home).

signup()​

An action for signing up the user. This action does not log in the user, you still need to call login().

It takes one argument:

  • userFields: object required

    It has the following fields:

    • username: string required

    • password: string required

    info

    By default, Wasp will only save the username and password fields. If you want to add extra fields to your signup process, read about defining extra signup fields.

You can use it like this:

src/pages/auth.jsx
import { signup, login } from 'wasp/client/auth'

import { useState } from 'react'
import { useHistory } from 'react-router-dom'
import { Link } from 'react-router-dom'

export function Signup() {
  const [username, setUsername] = useState('')
  const [password, setPassword] = useState('')
  const [error, setError] = useState(null)
  const history = useHistory()

  async function handleSubmit(event) {
    event.preventDefault()
    try {
      await signup({
        username,
        password,
      })
      await login(username, password)
      history.push("/")
    } catch (error) {
      setError(error)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* ... */}
    </form>
  );
}

2. Creating your custom sign-up action​

The code of your custom sign-up action can look like this:

main.wasp
// ...

action customSignup {
  fn: import { signup } from "@src/auth/signup.js",
}
src/auth/signup.js
import {
  ensurePasswordIsPresent,
  ensureValidPassword,
  ensureValidUsername,
  createProviderId,
  sanitizeAndSerializeProviderData,
  createUser,
} from 'wasp/server/auth'

export const signup = async (args, _context) => {
  ensureValidUsername(args)
  ensurePasswordIsPresent(args)
  ensureValidPassword(args)

  try {
    const providerId = createProviderId('username', args.username)
    const providerData = await sanitizeAndSerializeProviderData({
      hashedPassword: args.password,
    })

    await createUser(
      providerId,
      providerData,
      // Any additional data you want to store on the User entity
      {},
    )
  } catch (e) {
    return {
      success: false,
      message: e.message,
    }
  }

  // Your custom code after sign-up.
  // ...

  return {
    success: true,
    message: 'User created successfully',
  }
}

We suggest using the built-in field validators for your authentication flow. You can import them from wasp/server/auth. These are the same validators that Wasp uses internally for the default authentication flow.

Username​

  • ensureValidUsername(args)

    Checks if the username is valid and throws an error if it's not. Read more about the validation rules here.

Password​

  • ensurePasswordIsPresent(args)

    Checks if the password is present and throws an error if it's not.

  • ensureValidPassword(args)

    Checks if the password is valid and throws an error if it's not. Read more about the validation rules here.

Using Auth​

To read more about how to set up the logout button and how to get access to the logged-in user in our client and server code, read the auth overview docs.

getUsername​

If you are looking to access the user's username in your code, you can do that by accessing the info about the user that is stored in the user.auth.identities array.

To make things a bit easier for you, Wasp offers the getUsername helper.

The getUsername helper returns the user's username or null if the user doesn't have a username auth identity.

src/MainPage.jsx
import { getUsername } from 'wasp/auth'

const MainPage = ({ user }) => {
  const username = getUsername(user)
  // ...
}
src/tasks.js
import { getUsername } from 'wasp/auth'

export const createTask = async (args, context) => {
  const username = getUsername(context.user)
  // ...
}

API Reference​

userEntity fields​

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {},
    },
    onAuthFailedRedirectTo: "/login"
  }
}

entity User {=psl
    id                        Int           @id @default(autoincrement())
psl=}

The user entity needs to have the following fields:

  • id required

    It can be of any type, but it needs to be marked with @id

You can add any other fields you want to the user entity. Make sure to also define them in the userSignupFields field if they need to be set during the sign-up process.

Fields in the usernameAndPassword dict​

main.wasp
app myApp {
  wasp: {
    version: "^0.11.0"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {
        userSignupFields: import { userSignupFields } from "@src/auth/email.js",
      },
    },
    onAuthFailedRedirectTo: "/login"
  }
}
// ...

userSignupFields: ExtImport​

userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

src/auth.js
import { defineUserSignupFields } from 'wasp/server/auth'

export const userSignupFields = defineUserSignupFields({
  address: (data) => {
    if (!data.address) {
      throw new Error('Address is required')
    }
    return data.address
  }
  phone: (data) => data.phone,
})
Read more about the `userSignupFields` function [here](./overview#1-defining-extra-fields).
+ + \ No newline at end of file diff --git a/docs/0.12.0/contact.html b/docs/0.12.0/contact.html index 777dc6bfa1..636e030481 100644 --- a/docs/0.12.0/contact.html +++ b/docs/0.12.0/contact.html @@ -19,13 +19,13 @@ - - + + -
-
- - +
+
+ + \ No newline at end of file diff --git a/docs/0.12.0/contributing.html b/docs/0.12.0/contributing.html index d70e33bb10..5bda21e044 100644 --- a/docs/0.12.0/contributing.html +++ b/docs/0.12.0/contributing.html @@ -19,13 +19,13 @@ - - + + -
-
Version: 0.12.0

Contributing

Any way you want to contribute is a good way, and we'd be happy to meet you! A single entry point for all contributors is the CONTRIBUTING.md file in our Github repo. All the requirements and instructions are there, so please check CONTRIBUTING.md for more details.

Some side notes to make your journey easier:

  1. Join us on Discord 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. That means you'll need to be somewhat familiar with this language if you'd like to contribute to the compiler itself. But Haskell is just a part of Wasp, and you can contribute to lot of parts that require web dev skills, either by coding or by suggesting how to improve Wasp and its design as a web framework. 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 and make an issue/PR!

Happy hacking!

- - +
+
Version: 0.12.0

Contributing

Any way you want to contribute is a good way, and we'd be happy to meet you! A single entry point for all contributors is the CONTRIBUTING.md file in our Github repo. All the requirements and instructions are there, so please check CONTRIBUTING.md for more details.

Some side notes to make your journey easier:

  1. Join us on Discord 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. That means you'll need to be somewhat familiar with this language if you'd like to contribute to the compiler itself. But Haskell is just a part of Wasp, and you can contribute to lot of parts that require web dev skills, either by coding or by suggesting how to improve Wasp and its design as a web framework. 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 and make an issue/PR!

Happy hacking!

+ + \ No newline at end of file diff --git a/docs/0.12.0/data-model/backends.html b/docs/0.12.0/data-model/backends.html index 9058689f87..f64138347a 100644 --- a/docs/0.12.0/data-model/backends.html +++ b/docs/0.12.0/data-model/backends.html @@ -19,12 +19,12 @@ - - + + -
-
Version: 0.12.0

Databases

Entities, Operations and Automatic CRUD together make a high-level interface for working with your app's data. Still, all that data has to live somewhere, so let's see how Wasp deals with databases.

Supported Database Backends​

Wasp supports multiple database backends. We'll list and explain each one.

SQLite​

The default database Wasp uses is SQLite.

SQLite is a great way for getting started with a new project because it doesn't require any configuration, but Wasp can only use it in development. Once you want to deploy your Wasp app to production, you'll need to switch to PostgreSQL and stick with it.

Fortunately, migrating from SQLite to PostgreSQL is pretty simple, and we have a guide to help you.

PostgreSQL​

PostgreSQL is the most advanced open-source database and one of the most popular databases overall. +

+
Version: 0.12.0

Databases

Entities, Operations and Automatic CRUD together make a high-level interface for working with your app's data. Still, all that data has to live somewhere, so let's see how Wasp deals with databases.

Supported Database Backends​

Wasp supports multiple database backends. We'll list and explain each one.

SQLite​

The default database Wasp uses is SQLite.

SQLite is a great way for getting started with a new project because it doesn't require any configuration, but Wasp can only use it in development. Once you want to deploy your Wasp app to production, you'll need to switch to PostgreSQL and stick with it.

Fortunately, migrating from SQLite to PostgreSQL is pretty simple, and we have a guide to help you.

PostgreSQL​

PostgreSQL is the most advanced open-source database and one of the most popular databases overall. It's been in active development for 20+ years. Therefore, if you're looking for a battle-tested database, look no further.

To use Wasp with PostgreSQL, you'll have to ensure a database instance is running during development. Wasp needs access to your database for commands such as wasp start or wasp db migrate-dev and expects to find a connection string in the DATABASE_URL environment variable.

We cover all supported ways of connecting to a database in the next section.

Migrating from SQLite to PostgreSQL​

To run your Wasp app in production, you'll need to switch from SQLite to PostgreSQL.

  1. Set the app.db.system field to PostgreSQL.
main.wasp
app MyApp {
  title: "My app",
  // ...
  db: {
    system: PostgreSQL,
    // ...
  }
}
  1. Delete all the old migrations, since they are SQLite migrations and can't be used with PostgreSQL, as well as the SQLite database by running wasp clean:
rm -r migrations/
wasp clean
  1. Ensure your new database is running (check the section on connecing to a database to see how). Leave it running, since we need it for the next step.
  2. In a different terminal, run wasp db migrate-dev to apply the changes and create a new initial migration.
  3. That is it, you are all done!

Connecting to a Database​

Assuming you're not using SQLite, Wasp offers two ways of connecting your app to a database instance:

  1. A ready-made dev database that requires minimal setup and is great for quick prototyping.
  2. A "real" database Wasp can connect to and use in production.

Using the Dev Database Provided by Wasp​

The command wasp start db will start a default PostgreSQL dev database for you.

Your Wasp app will automatically connect to it, just keep wasp start db running in the background. Also, make sure that:

Connecting to an existing database​

If you want to spin up your own dev database (or connect to an external one), you can tell Wasp about it using the DATABASE_URL environment variable. Wasp will use the value of DATABASE_URL as a connection string.

The easiest way to set the necessary DATABASE_URL environment variable is by adding it to the .env.server file in the root dir of your Wasp project (if that file doesn't yet exist, create it).

Alternatively, you can set it inline when running wasp (this applies to all environment variables):

DATABASE_URL=<my-db-url> wasp ...

This trick is useful for running a certain wasp command on a specific database. @@ -36,7 +36,7 @@ Whenever you modify the db.system field, make sure to run wasp db migrate-dev to apply the changes.

  • seeds: [ExtImport]

    Defines the seed functions you can use with the wasp db seed command to seed your database with initial data. Read the Seeding section for more details.

  • prisma: PrismaOptions

    Additional configuration for Prisma.

    main.wasp
    app MyApp {
      // ...
      db: {
        // ...
        prisma: {
          clientPreviewFeatures: ["postgresqlExtensions"],
          dbExtensions: [
            { name: "hstore", schema: "myHstoreSchema" },
            { name: "pg_trgm" },
            { name: "postgis", version: "2.1" },
          ]
        }
      }
    }

    It's a dictionary with the following fields:

    • clientPreviewFeatures : [string]

      Allows you to define Prisma client preview features, like for example, "postgresqlExtensions".

    • dbExtensions: DbExtension[]

      It allows you to define PostgreSQL extensions that should be enabled for your database. Read more about PostgreSQL extensions in Prisma.

      For each extension you define a dict with the following fields:

      • name: string required

        The name of the extension you would normally put in the Prisma file.

        schema.prisma
        extensions = [hstore(schema: "myHstoreSchema"), pg_trgm, postgis(version: "2.1")]
        //              👆 Extension name

      • map: string

        It sets the map argument of the extension. Explanation for the field from the Prisma docs:

        This is the database name of the extension. If this argument is not specified, the name of the extension in the Prisma schema must match the database name.

      • schema: string

        It sets the schema argument of the extension. Explanation for the field from the Prisma docs:

        This is the name of the schema in which to activate the extension's objects. If this argument is not specified, the current default object creation schema is used.

      • version: string

        It sets the version argument of the extension. Explanation for the field from the Prisma docs:

        This is the version of the extension to activate. If this argument is not specified, the value given in the extension's control file is used.

    • CLI Commands for Seeding the Database​

    Use one of the following commands to run the seed functions:

    • wasp db seed

      If you've only defined a single seed function, this command runs it. If you've defined multiple seed functions, it asks you to choose one interactively.

    • wasp db seed <seed-name>

      This command runs the seed function with the specified name. The name is the identifier used in its import expression in the app.db.seeds list. For example, to run the seed function devSeedSimple which was defined like this:

      main.wasp
      app MyApp {
        // ...
        db: {
          // ...
          seeds: [
            // ...
            import { devSeedSimple } from "@src/dbSeeds.js",
          ]
        }
      }

      Use the following command:

      wasp db seed devSeedSimple
    - - + + \ No newline at end of file diff --git a/docs/0.12.0/data-model/crud.html b/docs/0.12.0/data-model/crud.html index 7269e7fba8..cbc859c6da 100644 --- a/docs/0.12.0/data-model/crud.html +++ b/docs/0.12.0/data-model/crud.html @@ -19,15 +19,15 @@ - - + + -
    -
    Version: 0.12.0

    Automatic CRUD

    If you have a lot of experience writing full-stack apps, you probably ended up doing some of the same things many times: listing data, adding data, editing it, and deleting it.

    Wasp makes handling these boring bits easy by offering a higher-level concept called Automatic CRUD.

    With a single declaration, you can tell Wasp to automatically generate server-side logic (i.e., Queries and Actions) for creating, reading, updating and deleting Entities. As you update definitions for your Entities, Wasp automatically regenerates the backend logic.

    Early preview

    This feature is currently in early preview and we are actively working on it. Read more about our plans for CRUD operations.

    Overview​

    Imagine we have a Task entity and we want to enable CRUD operations for it.

    main.wasp
    entity Task {=psl
      id          Int @id @default(autoincrement())
      description String
      isDone      Boolean
    psl=}

    We can then define a new crud called Tasks.

    We specify to use the Task entity and we enable the getAll, get, create and update operations (let's say we don't need the delete operation).

    main.wasp
    crud Tasks {
      entity: Task,
      operations: {
        getAll: {
          isPublic: true, // by default only logged in users can perform operations
        },
        get: {},
        create: {
          overrideFn: import { createTask } from "@src/tasks.js",
        },
        update: {},
      },
    }
    1. It uses default implementation for getAll, get, and update,
    2. ... while specifying a custom implementation for create.
    3. getAll will be public (no auth needed), while the rest of the operations will be private.

    Here's what it looks like when visualized:

    Automatic CRUD with Wasp
    Visualization of the Tasks crud declaration

    We can now use the CRUD queries and actions we just specified in our client code.

    Keep reading for an example of Automatic CRUD in action, or skip ahead for the API Reference

    Example: A Simple TODO App​

    Let's create a full-app example that uses automatic CRUD. We'll stick to using the Task entity from the previous example, but we'll add a User entity and enable username and password based auth.

    Automatic CRUD with Wasp
    We are building a simple tasks app with username based auth

    Creating the App​

    We can start by running wasp new tasksCrudApp and then adding the following to the main.wasp file:

    main.wasp
    app tasksCrudApp {
      wasp: {
        version: "^0.11.0"
      },
      title: "Tasks Crud App",

      // We enabled auth and set the auth method to username and password
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login",
      },
    }

    entity User {=psl
      id       Int @id @default(autoincrement())
      tasks    Task[]
    psl=}

    // We defined a Task entity on which we'll enable CRUD later on
    entity Task {=psl
      id          Int @id @default(autoincrement())
      description String
      isDone      Boolean
      userId      Int
      user        User @relation(fields: [userId], references: [id])
    psl=}

    // Tasks app routes
    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      component: import { MainPage } from "@src/MainPage.jsx",
      authRequired: true,
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage.jsx",
    }

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage.jsx",
    }

    We can then run wasp db migrate-dev to create the database and run the migrations.

    Adding CRUD to the Task Entity ✨​

    Let's add the following crud declaration to our main.wasp file:

    main.wasp
    // ...

    crud Tasks {
      entity: Task,
      operations: {
        getAll: {},
        create: {
          overrideFn: import { createTask } from "@src/tasks.js",
        },
      },
    }

    You'll notice that we enabled only getAll and create operations. This means that only these operations will be available.

    We also overrode the create operation with a custom implementation. This means that the create operation will not be generated, but instead, the createTask function from @src/tasks.js will be used.

    Our Custom create Operation​

    Here's the src/tasks.ts file:

    src/tasks.js
    import { HttpError } from 'wasp/server'

    export const createTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401, 'User not authenticated.')
      }

      const { description, isDone } = args
      const { Task } = context.entities

      return await Task.create({
        data: {
          description,
          isDone,
          // Connect the task to the user that is creating it
          user: {
            connect: {
              id: context.user.id,
            },
          },
        },
      })
    }

    We made a custom create operation because we want to make sure that the task is connected to the user that is creating it. +

    +
    Version: 0.12.0

    Automatic CRUD

    If you have a lot of experience writing full-stack apps, you probably ended up doing some of the same things many times: listing data, adding data, editing it, and deleting it.

    Wasp makes handling these boring bits easy by offering a higher-level concept called Automatic CRUD.

    With a single declaration, you can tell Wasp to automatically generate server-side logic (i.e., Queries and Actions) for creating, reading, updating and deleting Entities. As you update definitions for your Entities, Wasp automatically regenerates the backend logic.

    Early preview

    This feature is currently in early preview and we are actively working on it. Read more about our plans for CRUD operations.

    Overview​

    Imagine we have a Task entity and we want to enable CRUD operations for it.

    main.wasp
    entity Task {=psl
      id          Int @id @default(autoincrement())
      description String
      isDone      Boolean
    psl=}

    We can then define a new crud called Tasks.

    We specify to use the Task entity and we enable the getAll, get, create and update operations (let's say we don't need the delete operation).

    main.wasp
    crud Tasks {
      entity: Task,
      operations: {
        getAll: {
          isPublic: true, // by default only logged in users can perform operations
        },
        get: {},
        create: {
          overrideFn: import { createTask } from "@src/tasks.js",
        },
        update: {},
      },
    }
    1. It uses default implementation for getAll, get, and update,
    2. ... while specifying a custom implementation for create.
    3. getAll will be public (no auth needed), while the rest of the operations will be private.

    Here's what it looks like when visualized:

    Automatic CRUD with Wasp
    Visualization of the Tasks crud declaration

    We can now use the CRUD queries and actions we just specified in our client code.

    Keep reading for an example of Automatic CRUD in action, or skip ahead for the API Reference

    Example: A Simple TODO App​

    Let's create a full-app example that uses automatic CRUD. We'll stick to using the Task entity from the previous example, but we'll add a User entity and enable username and password based auth.

    Automatic CRUD with Wasp
    We are building a simple tasks app with username based auth

    Creating the App​

    We can start by running wasp new tasksCrudApp and then adding the following to the main.wasp file:

    main.wasp
    app tasksCrudApp {
      wasp: {
        version: "^0.11.0"
      },
      title: "Tasks Crud App",

      // We enabled auth and set the auth method to username and password
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login",
      },
    }

    entity User {=psl
      id       Int @id @default(autoincrement())
      tasks    Task[]
    psl=}

    // We defined a Task entity on which we'll enable CRUD later on
    entity Task {=psl
      id          Int @id @default(autoincrement())
      description String
      isDone      Boolean
      userId      Int
      user        User @relation(fields: [userId], references: [id])
    psl=}

    // Tasks app routes
    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      component: import { MainPage } from "@src/MainPage.jsx",
      authRequired: true,
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage.jsx",
    }

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage.jsx",
    }

    We can then run wasp db migrate-dev to create the database and run the migrations.

    Adding CRUD to the Task Entity ✨​

    Let's add the following crud declaration to our main.wasp file:

    main.wasp
    // ...

    crud Tasks {
      entity: Task,
      operations: {
        getAll: {},
        create: {
          overrideFn: import { createTask } from "@src/tasks.js",
        },
      },
    }

    You'll notice that we enabled only getAll and create operations. This means that only these operations will be available.

    We also overrode the create operation with a custom implementation. This means that the create operation will not be generated, but instead, the createTask function from @src/tasks.js will be used.

    Our Custom create Operation​

    Here's the src/tasks.ts file:

    src/tasks.js
    import { HttpError } from 'wasp/server'

    export const createTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401, 'User not authenticated.')
      }

      const { description, isDone } = args
      const { Task } = context.entities

      return await Task.create({
        data: {
          description,
          isDone,
          // Connect the task to the user that is creating it
          user: {
            connect: {
              id: context.user.id,
            },
          },
        },
      })
    }

    We made a custom create operation because we want to make sure that the task is connected to the user that is creating it. Automatic CRUD doesn't support this by default (yet!). Read more about the default implementations here.

    Using the Generated CRUD Operations on the Client​

    And let's use the generated operations in our client code:

    src/MainPage.jsx
    import { Tasks } from 'wasp/client/crud'
    import { useState } from 'react'

    export const MainPage = () => {
      const { data: tasks, isLoading, error } = Tasks.getAll.useQuery()
      const createTask = Tasks.create.useAction()
      const [taskDescription, setTaskDescription] = useState('')

      function handleCreateTask() {
        createTask({ description: taskDescription, isDone: false })
        setTaskDescription('')
      }

      if (isLoading) return <div>Loading...</div>
      if (error) return <div>Error: {error.message}</div>
      return (
        <div
          style={{
            fontSize: '1.5rem',
            display: 'grid',
            placeContent: 'center',
            height: '100vh',
          }}
        >
          <div>
            <input
              value={taskDescription}
              onChange={(e) => setTaskDescription(e.target.value)}
            />
            <button onClick={handleCreateTask}>Create task</button>
          </div>
          <ul>
            {tasks.map((task) => (
              <li key={task.id}>{task.description}</li>
            ))}
          </ul>
        </div>
      )
    }

    And here are the login and signup pages, where we are using Wasp's Auth UI components:

    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'
    import { Link } from 'react-router-dom'

    export function LoginPage() {
      return (
        <div
          style={{
            display: 'grid',
            placeContent: 'center',
          }}
        >
          <LoginForm />
          <div>
            <Link to="/signup">Create an account</Link>
          </div>
        </div>
      )
    }
    src/SignupPage.jsx
    import { SignupForm } from 'wasp/client/auth'

    export function SignupPage() {
      return (
        <div
          style={{
            display: 'grid',
            placeContent: 'center',
          }}
        >
          <SignupForm />
        </div>
      )
    }

    That's it. You can now run wasp start and see the app in action. ⚡️

    You should see a login page and a signup page. After you log in, you should see a page with a list of tasks and a form to create new tasks.

    Future of CRUD Operations in Wasp​

    CRUD operations currently have a limited set of knowledge about the business logic they are implementing.

    • For example, they don't know that a task should be connected to the user that is creating it. This is why we had to override the create operation in the example above.
    • Another thing: they are not aware of the authorization rules. For example, they don't know that a user should not be able to create a task for another user. In the future, we will be adding role-based authorization to Wasp, and we plan to make CRUD operations aware of the authorization rules.
    • Another issue is input validation and sanitization. For example, we might want to make sure that the task description is not empty.

    CRUD operations are a mechanism for getting a backend up and running quickly, but it depends on the information it can get from the Wasp app. The more information that it can pick up from your app, the more powerful it will be out of the box.

    We plan on supporting CRUD operations and growing them to become the easiest way to create your backend. Follow along on this GitHub issue to see how we are doing.

    API Reference​

    CRUD declaration work on top of existing entity declaration. We'll fully explore the API using two examples:

    1. A basic CRUD declaration that relies on default options.
    2. A more involved CRUD declaration that uses extra options and overrides.

    Declaring a CRUD With Default Options​

    If we create CRUD operations for an entity named Task, like this:

    main.wasp
    crud Tasks { // crud name here is "Tasks"
      entity: Task,
      operations: {
        get: {},
        getAll: {},
        create: {},
        update: {},
        delete: {},
      },
    }

    Wasp will give you the following default implementations:

    get - returns one entity based on the id field

    // ...
    // Wasp uses the field marked with `@id` in Prisma schema as the id field.
    return Task.findUnique({ where: { id: args.id } })

    getAll - returns all entities

    // ...

    // If the operation is not public, Wasp checks if an authenticated user
    // is making the request.

    return Task.findMany()

    create - creates a new entity

    // ...
    return Task.create({ data: args.data })

    update - updates an existing entity

    // ...
    // Wasp uses the field marked with `@id` in Prisma schema as the id field.
    return Task.update({ where: { id: args.id }, data: args.data })

    delete - deletes an existing entity

    // ...
    // Wasp uses the field marked with `@id` in Prisma schema as the id field.
    return Task.delete({ where: { id: args.id } })
    Current Limitations

    In the default create and update implementations, we are saving all of the data that the client sends to the server. This is not always desirable, i.e. in the case when the client should not be able to modify all of the data in the entity.

    In the future, we are planning to add validation of action input, where only the data that the user is allowed to change will be saved.

    For now, the solution is to provide an override function. You can override the default implementation by using the overrideFn option and implementing the validation logic yourself.

    Declaring a CRUD With All Available Options​

    Here's an example of a more complex CRUD declaration:

    main.wasp
    crud Tasks { // crud name here is "Tasks"
      entity: Task,
      operations: {
        getAll: {
          isPublic: true, // optional, defaults to false
        },
        get: {},
        create: {
          overrideFn: import { createTask } from "@src/tasks.js", // optional
        },
        update: {},
      },
    }

    The CRUD declaration features the following fields:

    • entity: Entity required

      The entity to which the CRUD operations will be applied.

    • operations: { [operationName]: CrudOperationOptions } required

      The operations to be generated. The key is the name of the operation, and the value is the operation configuration.

      • The possible values for operationName are:
        • getAll
        • get
        • create
        • update
        • delete
      • CrudOperationOptions can have the following fields:
        • isPublic: bool - Whether the operation is public or not. If it is public, no auth is required to access it. If it is not public, it will be available only to authenticated users. Defaults to false.
        • overrideFn: ExtImport - The import statement of the optional override implementation in Node.js.

    Defining the overrides​

    Like with actions and queries, you can define the implementation in a Javascript/Typescript file. The overrides are functions that take the following arguments:

    • args

      The arguments of the operation i.e. the data sent from the client.

    • context

      Context contains the user making the request and the entities object with the entity that's being operated on.

    For a usage example, check the example guide.

    Using the CRUD operations in client code​

    On the client, you import the CRUD operations from wasp/client/crud by import the {crud name} object. For example, if you have a CRUD called Tasks, you would import the operations like this:

    SomePage.jsx
    import { Tasks } from 'wasp/client/crud'

    You can then access the operations like this:

    SomePage.jsx
    const { data } = Tasks.getAll.useQuery()
    const { data } = Tasks.get.useQuery({ id: 1 })
    const createAction = Tasks.create.useAction()
    const updateAction = Tasks.update.useAction()
    const deleteAction = Tasks.delete.useAction()

    All CRUD operations are implemented with Queries and Actions under the hood, which means they come with all the features you'd expect (e.g., automatic SuperJSON serialization, full-stack type safety when using TypeScript)

    Join our community on Discord, where we chat about full-stack web stuff. Join us to see what we are up to, share your opinions or get help with CRUD operations.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/data-model/entities.html b/docs/0.12.0/data-model/entities.html index b94a217a3f..270cdcc3e8 100644 --- a/docs/0.12.0/data-model/entities.html +++ b/docs/0.12.0/data-model/entities.html @@ -19,15 +19,15 @@ - - + + -
    -
    Version: 0.12.0

    Entities

    Entities are the foundation of your app's data model. In short, an Entity defines a model in your database.

    Wasp uses the excellent Prisma ORM to implement all database functionality and occasionally enhances it with a thin abstraction layer. +

    +
    Version: 0.12.0

    Entities

    Entities are the foundation of your app's data model. In short, an Entity defines a model in your database.

    Wasp uses the excellent Prisma ORM to implement all database functionality and occasionally enhances it with a thin abstraction layer. Wasp Entities directly correspond to Prisma's data model. Still, you don't need to be familiar with Prisma to effectively use Wasp, as it comes with a simple API wrapper for working with Prisma's core features.

    The only requirement for defining Wasp Entities is familiarity with the Prisma Schema Language (PSL), a simple definition language explicitly created for defining models in Prisma. The language is declarative and very intuitive. We'll also go through an example later in the text, so there's no need to go and thoroughly learn it right away. Still, if you're curious, look no further than Prisma's official documentation:

    Defining an Entity​

    As mentioned, an entity declaration represents a database model.

    Each Entity declaration corresponds 1-to-1 to Prisma's data model. Here's how you could define an Entity that represents a Task:

    entity Task {=psl
        id          Int     @id @default(autoincrement())
        description String
        isDone      Boolean @default(false)
    psl=}

    Let's go through this declaration in detail:

    • entity Task - This tells Wasp that we wish to define an Entity (i.e., database model) called Task. Wasp automatically creates a table called tasks.
    • {=psl ... psl=} - Wasp treats everything that comes between the two psl tags as PSL (Prisma Schema Language).

    The above PSL definition tells Wasp to create a table for storing Tasks where each task has three fields (i.e., the tasks table has three columns):

    • id - An integer value serving as a primary key. The database automatically generates it by incrementing the previously generated id.
    • description - A string value for storing the task's description.
    • isDone - A boolean value indicating the task's completion status. If you don't set it when creating a new task, the database sets it to false by default.

    Working with Entities​

    Let's see how you can define and work with Wasp Entities:

    1. Create/update some Entities in your .wasp file.
    2. Run wasp db migrate-dev. This command syncs the database model with the Entity definitions in your .wasp file. It does this by creating migration scripts.
    3. Migration scripts are automatically placed in the migrations/ folder. Make sure to commit this folder into version control.
    4. Use Wasp's JavasScript API to work with the database when implementing Operations (we'll cover this in detail when we talk about operations).

    Using Entities in Operations​

    Most of the time, you will be working with Entities within the context of Operations (Queries & Actions). We'll see how that's done on the next page.

    Using Entities directly​

    If you need more control, you can directly interact with Entities by importing and using the Prisma Client. We recommend sticking with conventional Wasp-provided mechanisms, only resorting to directly using the Prisma client only if you need a feature Wasp doesn't provide.

    You can only use the Prisma Client in your Wasp server code. You can import it like this:

    import { prisma } from 'wasp/server'

    prisma.task.create({
        description: "Read the Entities doc",
        isDone: true // almost :)
    })

    Next steps​

    Now that we've seen how to define Entities that represent Wasp's core data model, we'll see how to make the most of them in other parts of Wasp. Keep reading to learn all about Wasp Operations!

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/data-model/operations/actions.html b/docs/0.12.0/data-model/operations/actions.html index 7c279e2b96..161e6cf392 100644 --- a/docs/0.12.0/data-model/operations/actions.html +++ b/docs/0.12.0/data-model/operations/actions.html @@ -19,12 +19,12 @@ - - + + -
    -
    Version: 0.12.0

    Actions

    We'll explain what Actions are and how to use them. If you're looking for a detailed API specification, skip ahead to the API Reference.

    Actions are quite similar to Queries, but with a key distinction: Actions are designed to modify and add data, while Queries are solely for reading data. Examples of Actions include adding a comment to a blog post, liking a video, or updating a product's price.

    Actions and Queries work together to keep data caches up-to-date.

    tip

    Actions are almost identical to Queries in terms of their API. +

    +
    Version: 0.12.0

    Actions

    We'll explain what Actions are and how to use them. If you're looking for a detailed API specification, skip ahead to the API Reference.

    Actions are quite similar to Queries, but with a key distinction: Actions are designed to modify and add data, while Queries are solely for reading data. Examples of Actions include adding a comment to a blog post, liking a video, or updating a product's price.

    Actions and Queries work together to keep data caches up-to-date.

    tip

    Actions are almost identical to Queries in terms of their API. Therefore, if you're already familiar with Queries, you might find reading the entire guide repetitive.

    We instead recommend skipping ahead and only reading the differences between Queries and Actions, and consulting the API Reference as needed.

    Working with Actions​

    Actions are declared in Wasp and implemented in NodeJS. Wasp runs Actions within the server's context, but it also generates code that allows you to call them from anywhere in your code (either client or server) using the same interface.

    This means you don't have to worry about building an HTTP API for the Action, managing server-side request handling, or even dealing with client-side response handling and caching. Instead, just focus on developing the business logic inside your Action, and let Wasp handle the rest!

    To create an Action, you need to:

    1. Declare the Action in Wasp using the action declaration.
    2. Implement the Action's NodeJS functionality.

    Once these two steps are completed, you can use the Action from anywhere in your code.

    Declaring Actions​

    To create an Action in Wasp, we begin with an action declaration. Let's declare two Actions - one for creating a task, and another for marking tasks as done:

    main.wasp
    // ...

    action createTask {
      fn: import { createTask } from "@src/actions.js"
    }

    action markTaskAsDone {
      fn: import { markTaskAsDone } from "@src/actions.js"
    }

    If you want to know about all supported options for the action declaration, take a look at the API Reference.

    The names of Wasp Actions and their implementations don't necessarily have to match. However, to avoid confusion, we'll keep them the same.

    tip

    Wasp uses superjson under the hood. This means you're not limited to only sending and receiving JSON payloads.

    You can send and receive any superjson-compatible payload (like Dates, Sets, Lists, circular references, etc.) and let Wasp handle the (de)serialization.

    After declaring a Wasp Action, two important things happen:

    • Wasp generates a server-side NodeJS function that shares its name with the Action.

    • Wasp generates a client-side JavaScript function that shares its name with the Action (e.g., markTaskAsDone). @@ -42,7 +42,7 @@ Since both arguments are positional, you can name the parameters however you want, but we'll stick with args and context:

      1. args (type depends on the Action)

        An object containing the data passed in when calling the Action (e.g., filtering conditions). Check the usage examples to see how to pass this object to the Action.

      2. context (type depends on the Action)

        An additional context object passed into the Action by Wasp. This object contains user session information, as well as information about entities. Check the section about using entities in Actions to see how to use the entities field on the context object, or the auth section to see how to use the user object.

      Example​

      The following Action:

      action createFoo {
          fn: import { createFoo } from "@src/actions.js"
          entities: [Foo]
      }

      Expects to find a named export createfoo from the file src/actions.js

      actions.js
      export const createFoo = (args, context) => {
        // implementation
      }

      The useAction Hook and Optimistic Updates​

      Make sure you understand how Queries and Cache Invalidation work before reading this chapter.

      When using Actions in components, you can enhance them with the help of the useAction hook. This hook comes bundled with Wasp, and is used for decorating Wasp Actions. In other words, the hook returns a function whose API matches the original Action while also doing something extra under the hood (depending on how you configure it).

      The useAction hook accepts two arguments:

      • actionFn required

        The Wasp Action (i.e., the client-side Action function generated by Wasp based on a Action declaration) you wish to enhance.

      • actionOptions

        An object configuring the extra features you want to add to the given Action. While this argument is technically optional, there is no point in using the useAction hook without providing it (it would be the same as using the Action directly). The Action options object supports the following fields:

        • optimisticUpdates

          An array of objects where each object defines an optimistic update to perform on the Query cache. To define an optimistic update, you must specify the following properties:

          • getQuerySpecifier required

          A function returning the Query specifier (i.e., a value used to address the Query you want to update). A Query specifier is an array specifying the query function and arguments. For example, to optimistically update the Query used with useQuery(fetchFilteredTasks, {isDone: true }], your getQuerySpecifier function would have to return the array [fetchFilteredTasks, { isDone: true}]. Wasp will forward the argument you pass into the decorated Action to this function (i.e., you can use the properties of the added/changed item to address the Query).

          • updateQuery required

          The function used to perform the optimistic update. It should return the desired state of the cache. Wasp will call it with the following arguments:

          • item - The argument you pass into the decorated Action.
          • oldData - The currently cached value for the Query identified by the specifier.
      caution

      The updateQuery function must be a pure function. It must return the desired cache value identified by the getQuerySpecifier function and must not perform any side effects.

      Also, make sure you only update the Query caches affected by your Action causing the optimistic update (Wasp cannot yet verify this).

      Finally, your implementation of the updateQuery function should work correctly regardless of the state of oldData (e.g., don't rely on array positioning). If you need to do something else during your optimistic update, you can directly use react-query's lower-level API (read more about it here).

      Here's an example showing how to configure the Action markTaskAsDone that toggles a task's isDone status to perform an optimistic update:

      src/pages/Task.jsx
      import React from 'react'
      import {
        useQuery,
        useAction,
        getTask,
        markTaskAsDone,
      } from 'wasp/client/operations'

      const TaskPage = ({ id }) => {
        const { data: task } = useQuery(getTask, { id })
        const markTaskAsDoneOptimistically = useAction(markTaskAsDone, {
          optimisticUpdates: [
            {
              getQuerySpecifier: ({ id }) => [getTask, { id }],
              updateQuery: (_payload, oldData) => ({ ...oldData, isDone: true }),
            },
          ],
        })

        if (!task) {
          return <h1>"Loading"</h1>
        }

        const { description, isDone } = task
        return (
          <div>
            <p>
              <strong>Description: </strong>
              {description}
            </p>
            <p>
              <strong>Is done: </strong>
              {isDone ? 'Yes' : 'No'}
            </p>
            {isDone || (
              <button onClick={() => markTaskAsDoneOptimistically({ id })}>
                Mark as done.
              </button>
            )}
          </div>
        )
      }

      export default TaskPage

      Advanced usage​

      The useAction hook currently only supports specifying optimistic updates. You can expect more features in future versions of Wasp.

      Wasp's optimistic update API is deliberately small and focuses exclusively on updating Query caches (as that's the most common use case). You might need an API that offers more options or a higher level of control. If that's the case, instead of using Wasp's useAction hook, you can use react-query's useMutation hook and directly work with their low-level API.

      If you decide to use react-query's API directly, you will need access to Query cache key. Wasp internally uses this key but abstracts it from the programmer. Still, you can easily obtain it by accessing the queryCacheKey property on any Query:

      import { getTasks } from 'wasp/client/operations'

      const queryKey = getTasks.queryCacheKey
    - - + + \ No newline at end of file diff --git a/docs/0.12.0/data-model/operations/overview.html b/docs/0.12.0/data-model/operations/overview.html index e313d97d91..6dd69686d4 100644 --- a/docs/0.12.0/data-model/operations/overview.html +++ b/docs/0.12.0/data-model/operations/overview.html @@ -19,14 +19,14 @@ - - + + -
    -
    Version: 0.12.0

    Overview

    While Entities enable help you define your app's data model and relationships, Operations are all about working with this data.

    There are two kinds of Operations: Queries and Actions. As their names suggest, +

    +
    - - + + \ No newline at end of file diff --git a/docs/0.12.0/data-model/operations/queries.html b/docs/0.12.0/data-model/operations/queries.html index b5af3a0831..8974072957 100644 --- a/docs/0.12.0/data-model/operations/queries.html +++ b/docs/0.12.0/data-model/operations/queries.html @@ -19,12 +19,12 @@ - - + + -
    -
    Version: 0.12.0

    Queries

    We'll explain what Queries are and how to use them. If you're looking for a detailed API specification, skip ahead to the API Reference.

    You can use Queries to fetch data from the server. They shouldn't modify the server's state. +

    +
    Version: 0.12.0

    Queries

    We'll explain what Queries are and how to use them. If you're looking for a detailed API specification, skip ahead to the API Reference.

    You can use Queries to fetch data from the server. They shouldn't modify the server's state. Fetching all comments on a blog post, a list of users that liked a video, information about a single product based on its ID... All of these are perfect use cases for a Query.

    tip

    Queries are fairly similar to Actions in terms of their API. Therefore, if you're already familiar with Actions, you might find reading the entire guide repetitive.

    We instead recommend skipping ahead and only reading the differences between Queries and Actions, and consulting the API Reference as needed.

    Working with Queries​

    You declare queries in the .wasp file and implement them using NodeJS. Wasp not only runs these queries within the server's context but also creates code that enables you to call them from any part of your codebase, whether it's on the client or server side.

    This means you don't have to build an HTTP API for your query, manage server-side request handling, or even deal with client-side response handling and caching. Instead, just concentrate on implementing the business logic inside your query, and let Wasp handle the rest!

    To create a Query, you must:

    1. Declare the Query in Wasp using the query declaration.
    2. Define the Query's NodeJS implementation.

    After completing these two steps, you'll be able to use the Query from any point in your code.

    Declaring Queries​

    To create a Query in Wasp, we begin with a query declaration.

    Let's declare two Queries - one to fetch all tasks, and another to fetch tasks based on a filter, such as whether a task is done:

    main.wasp
    // ...

    query getAllTasks {
      fn: import { getAllTasks } from "@src/queries.js"
    }

    query getFilteredTasks {
      fn: import { getFilteredTasks } from "@src/queries.js"
    }

    If you want to know about all supported options for the query declaration, take a look at the API Reference.

    The names of Wasp Queries and their implementations don't need to match, but we'll keep them the same to avoid confusion.

    info

    You might have noticed that we told Wasp to import Query implementations that don't yet exist. Don't worry about that for now. We'll write the implementations imported from queries.ts in the next section.

    It's a good idea to start with the high-level concept (i.e., the Query declaration in the Wasp file) and only then deal with the implementation details (i.e., the Query's implementation in JavaScript).

    After declaring a Wasp Query, two important things happen:

    • Wasp generates a server-side NodeJS function that shares its name with the Query.

    • Wasp generates a client-side JavaScript function that shares its name with the Query (e.g., getFilteredTasks). @@ -46,7 +46,7 @@ behavior for this particular Query. If you want to change the global defaults, you can do so in the client setup function.

    For an example of usage, check this section.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/editor-setup.html b/docs/0.12.0/editor-setup.html index 0dfca86d75..56977c6eda 100644 --- a/docs/0.12.0/editor-setup.html +++ b/docs/0.12.0/editor-setup.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.12.0

    Editor Setup

    note

    This page assumes you have already installed Wasp. If you do not have Wasp installed yet, check out the Quick Start guide.

    Wasp comes with the Wasp language server, which gives supported editors powerful support and integration with the language.

    VSCode​

    Currently, Wasp only supports integration with VSCode. Install the Wasp language extension to get syntax highlighting and integration with the Wasp language server.

    The extension enables:

    • syntax highlighting for .wasp files
    • scaffolding of new project files
    • code completion
    • diagnostics (errors and warnings)
    • go to definition

    and more!

    - - +
    +
    Version: 0.12.0

    Editor Setup

    note

    This page assumes you have already installed Wasp. If you do not have Wasp installed yet, check out the Quick Start guide.

    Wasp comes with the Wasp language server, which gives supported editors powerful support and integration with the language.

    VSCode​

    Currently, Wasp only supports integration with VSCode. Install the Wasp language extension to get syntax highlighting and integration with the Wasp language server.

    The extension enables:

    • syntax highlighting for .wasp files
    • scaffolding of new project files
    • code completion
    • diagnostics (errors and warnings)
    • go to definition

    and more!

    + + \ No newline at end of file diff --git a/docs/0.12.0/general/cli.html b/docs/0.12.0/general/cli.html index 773bbab723..976171b4b0 100644 --- a/docs/0.12.0/general/cli.html +++ b/docs/0.12.0/general/cli.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.12.0

    CLI Reference

    This guide provides an overview of the Wasp CLI commands, arguments, and options.

    Overview​

    Once installed, you can use the wasp command from your command line.

    If you run the wasp command without any arguments, it will show you a list of available commands and their descriptions:

    USAGE
      wasp <command> [command-args]

    COMMANDS
      GENERAL
        new [<name>] [args]   Creates a new Wasp project. Run it without arguments for interactive mode.
          OPTIONS:
            -t|--template <template-name>
               Check out the templates list here: https://github.com/wasp-lang/starters

        new:ai <app-name> <app-description> [<config-json>]
          Uses AI to create a new Wasp project just based on the app name and the description.
          You can do the same thing with `wasp new` interactively.
          Run `wasp new:ai` for more info.

        version               Prints current version of CLI.
        waspls                Run Wasp Language Server. Add --help to get more info.
        completion            Prints help on bash completion.
        uninstall             Removes Wasp from your system.
      IN PROJECT
        start                 Runs Wasp app in development mode, watching for file changes.
        start db              Starts managed development database for you.
        db <db-cmd> [args]    Executes a database command. Run 'wasp db' for more info.
        clean                 Deletes all generated code, all cached artifacts, and the node_modules dir.
                              Wasp equivalent of 'have you tried closing and opening it again?'.
        build                 Generates full web app code, ready for deployment. Use when deploying or ejecting.
        deploy                Deploys your Wasp app to cloud hosting providers.
        telemetry             Prints telemetry status.
        deps                  Prints the dependencies that Wasp uses in your project.
        dockerfile            Prints the contents of the Wasp generated Dockerfile.
        info                  Prints basic information about the current Wasp project.
        test                  Executes tests in your project.
        studio                (experimental) GUI for inspecting your Wasp app.

    EXAMPLES
      wasp new MyApp
      wasp start
      wasp db migrate-dev

    Docs: https://wasp-lang.dev/docs
    Discord (chat): https://discord.gg/rzdnErX
    Newsletter: https://wasp-lang.dev/#signup

    Commands​

    Creating a New Project​

    • Use wasp new to start the interactive mode for setting up a new Wasp project.

      This will prompt you to input the project name and to select a template. The chosen template will then be used to generate the project directory with the specified name.

      $ wasp new
      Enter the project name (e.g. my-project) ▸ MyFirstProject
      Choose a starter template
      [1] basic (default)
          Simple starter template with a single page.
      [2] todo-ts
          Simple but well-rounded Wasp app implemented with Typescript & full-stack type safety.
      [3] saas
          Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check out https://opensaas.sh/ for more details.
      [4] embeddings
          Comes with code for generating vector embeddings and performing vector similarity search.
      [5] ai-generated
          🤖 Describe an app in a couple of sentences and have Wasp AI generate initial code for you. (experimental)
      ▸ 1

      🐝 --- Creating your project from the "basic" template... -------------------------

      Created new Wasp app in ./MyFirstProject directory!

      To run your new app, do:
          cd MyFirstProject
          wasp db start

    • To skip the interactive mode and create a new Wasp project with the default template, use wasp new <project-name>.

      $ wasp new MyFirstProject
      🐝 --- Creating your project from the "basic" template... -------------------------

      Created new Wasp app in ./MyFirstProject directory!

      To run your new app, do:
         cd MyFirstProject
         wasp db start

    Project Commands​

    • wasp start launches the Wasp app in development mode. It automatically opens a browser tab with your application running and watches for any changes to .wasp or files in src/ to automatically reflect in the browser. It also shows messages from the web app, the server and the database on stdout/stderr.

    • wasp start db starts the database for you. This can be very handy since you don't need to spin up your own database or provide its connection URL to the Wasp app.

    • wasp clean removes all generated code and other cached artifacts. If using SQlite, it also deletes the SQlite database. Think of this as the Wasp version of the classic "turn it off and on again" solution.

      $ wasp clean

      🐝 --- Deleting the .wasp/ directory... -------------------------------------------

      ✅ --- Deleted the .wasp/ directory. ----------------------------------------------

      🐝 --- Deleting the node_modules/ directory... ------------------------------------

      ✅ --- Deleted the node_modules/ directory. ---------------------------------------

    • wasp build generates the complete web app code, which is ready for deployment. Use this command when you're deploying or ejecting. The generated code is stored in the .wasp/build folder.

    • wasp deploy makes it easy to get your app hosted on the web.

      Currently, Wasp offers support for Fly.io. If you prefer a different hosting provider, feel free to let us know on Discord or submit a PR by updating this TypeScript app.

      Read more about automatic deployment here.

    • wasp telemetry displays the status of telemetry.

      $ wasp telemetry

      Telemetry is currently: ENABLED
      Telemetry cache directory: /home/user/.cache/wasp/telemetry/
      Last time telemetry data was sent for this project: 2021-05-27 09:21:16.79537226 UTC
      Our telemetry is anonymized and very limited in its scope: check https://wasp-lang.dev/docs/telemetry for more details.

    • wasp deps lists the dependencies that Wasp uses in your project.

    • wasp info provides basic details about the current Wasp project.

    • wasp studio shows you an graphical overview of your application in a graph: pages, queries, actions, data model etc.

    Database Commands​

    Wasp provides a suite of commands for managing the database. These commands all begin with db and primarily execute Prisma commands behind the scenes.

    • wasp db migrate-dev synchronizes the development database with the current state of the schema (entities). If there are any changes in the schema, it generates a new migration and applies any pending migrations to the database.

      • The --name foo option allows you to specify a name for the migration, while the --create-only option lets you create an empty migration without applying it.

    • wasp db studio opens the GUI for inspecting your database.

    Bash Completion​

    To set up Bash completion, run the wasp completion command and follow the instructions.

    Miscellaneous Commands​

    • wasp version displays the current version of the CLI.

      $ wasp version

      0.12.0

      If you wish to install/switch to the latest version of Wasp, do:
      curl -sSL https://get.wasp-lang.dev/installer.sh | sh -s

      If you want specific x.y.z version of Wasp, do:
      curl -sSL https://get.wasp-lang.dev/installer.sh | sh -s -- -v x.y.z

      Check https://github.com/wasp-lang/wasp/releases for the list of valid versions, including the latest one.

    • wasp uninstall removes Wasp from your system.

      $ wasp uninstall

      🐝 --- Uninstalling Wasp ... ------------------------------------------------------

       We will remove the following directories:
         {home}/.local/share/wasp-lang/
         {home}/.cache/wasp/

       We will also remove the following files:
         {home}/.local/bin/wasp

       Are you sure you want to continue? [y/N]
       y

       ✅ --- Uninstalled Wasp -----------------------------------------------------------
    - - +
    +
    Version: 0.12.0

    CLI Reference

    This guide provides an overview of the Wasp CLI commands, arguments, and options.

    Overview​

    Once installed, you can use the wasp command from your command line.

    If you run the wasp command without any arguments, it will show you a list of available commands and their descriptions:

    USAGE
      wasp <command> [command-args]

    COMMANDS
      GENERAL
        new [<name>] [args]   Creates a new Wasp project. Run it without arguments for interactive mode.
          OPTIONS:
            -t|--template <template-name>
               Check out the templates list here: https://github.com/wasp-lang/starters

        new:ai <app-name> <app-description> [<config-json>]
          Uses AI to create a new Wasp project just based on the app name and the description.
          You can do the same thing with `wasp new` interactively.
          Run `wasp new:ai` for more info.

        version               Prints current version of CLI.
        waspls                Run Wasp Language Server. Add --help to get more info.
        completion            Prints help on bash completion.
        uninstall             Removes Wasp from your system.
      IN PROJECT
        start                 Runs Wasp app in development mode, watching for file changes.
        start db              Starts managed development database for you.
        db <db-cmd> [args]    Executes a database command. Run 'wasp db' for more info.
        clean                 Deletes all generated code, all cached artifacts, and the node_modules dir.
                              Wasp equivalent of 'have you tried closing and opening it again?'.
        build                 Generates full web app code, ready for deployment. Use when deploying or ejecting.
        deploy                Deploys your Wasp app to cloud hosting providers.
        telemetry             Prints telemetry status.
        deps                  Prints the dependencies that Wasp uses in your project.
        dockerfile            Prints the contents of the Wasp generated Dockerfile.
        info                  Prints basic information about the current Wasp project.
        test                  Executes tests in your project.
        studio                (experimental) GUI for inspecting your Wasp app.

    EXAMPLES
      wasp new MyApp
      wasp start
      wasp db migrate-dev

    Docs: https://wasp-lang.dev/docs
    Discord (chat): https://discord.gg/rzdnErX
    Newsletter: https://wasp-lang.dev/#signup

    Commands​

    Creating a New Project​

    • Use wasp new to start the interactive mode for setting up a new Wasp project.

      This will prompt you to input the project name and to select a template. The chosen template will then be used to generate the project directory with the specified name.

      $ wasp new
      Enter the project name (e.g. my-project) ▸ MyFirstProject
      Choose a starter template
      [1] basic (default)
          Simple starter template with a single page.
      [2] todo-ts
          Simple but well-rounded Wasp app implemented with Typescript & full-stack type safety.
      [3] saas
          Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check out https://opensaas.sh/ for more details.
      [4] embeddings
          Comes with code for generating vector embeddings and performing vector similarity search.
      [5] ai-generated
          🤖 Describe an app in a couple of sentences and have Wasp AI generate initial code for you. (experimental)
      ▸ 1

      🐝 --- Creating your project from the "basic" template... -------------------------

      Created new Wasp app in ./MyFirstProject directory!

      To run your new app, do:
          cd MyFirstProject
          wasp db start

    • To skip the interactive mode and create a new Wasp project with the default template, use wasp new <project-name>.

      $ wasp new MyFirstProject
      🐝 --- Creating your project from the "basic" template... -------------------------

      Created new Wasp app in ./MyFirstProject directory!

      To run your new app, do:
         cd MyFirstProject
         wasp db start

    Project Commands​

    • wasp start launches the Wasp app in development mode. It automatically opens a browser tab with your application running and watches for any changes to .wasp or files in src/ to automatically reflect in the browser. It also shows messages from the web app, the server and the database on stdout/stderr.

    • wasp start db starts the database for you. This can be very handy since you don't need to spin up your own database or provide its connection URL to the Wasp app.

    • wasp clean removes all generated code and other cached artifacts. If using SQlite, it also deletes the SQlite database. Think of this as the Wasp version of the classic "turn it off and on again" solution.

      $ wasp clean

      🐝 --- Deleting the .wasp/ directory... -------------------------------------------

      ✅ --- Deleted the .wasp/ directory. ----------------------------------------------

      🐝 --- Deleting the node_modules/ directory... ------------------------------------

      ✅ --- Deleted the node_modules/ directory. ---------------------------------------

    • wasp build generates the complete web app code, which is ready for deployment. Use this command when you're deploying or ejecting. The generated code is stored in the .wasp/build folder.

    • wasp deploy makes it easy to get your app hosted on the web.

      Currently, Wasp offers support for Fly.io. If you prefer a different hosting provider, feel free to let us know on Discord or submit a PR by updating this TypeScript app.

      Read more about automatic deployment here.

    • wasp telemetry displays the status of telemetry.

      $ wasp telemetry

      Telemetry is currently: ENABLED
      Telemetry cache directory: /home/user/.cache/wasp/telemetry/
      Last time telemetry data was sent for this project: 2021-05-27 09:21:16.79537226 UTC
      Our telemetry is anonymized and very limited in its scope: check https://wasp-lang.dev/docs/telemetry for more details.

    • wasp deps lists the dependencies that Wasp uses in your project.

    • wasp info provides basic details about the current Wasp project.

    • wasp studio shows you an graphical overview of your application in a graph: pages, queries, actions, data model etc.

    Database Commands​

    Wasp provides a suite of commands for managing the database. These commands all begin with db and primarily execute Prisma commands behind the scenes.

    • wasp db migrate-dev synchronizes the development database with the current state of the schema (entities). If there are any changes in the schema, it generates a new migration and applies any pending migrations to the database.

      • The --name foo option allows you to specify a name for the migration, while the --create-only option lets you create an empty migration without applying it.

    • wasp db studio opens the GUI for inspecting your database.

    Bash Completion​

    To set up Bash completion, run the wasp completion command and follow the instructions.

    Miscellaneous Commands​

    • wasp version displays the current version of the CLI.

      $ wasp version

      0.12.0

      If you wish to install/switch to the latest version of Wasp, do:
      curl -sSL https://get.wasp-lang.dev/installer.sh | sh -s

      If you want specific x.y.z version of Wasp, do:
      curl -sSL https://get.wasp-lang.dev/installer.sh | sh -s -- -v x.y.z

      Check https://github.com/wasp-lang/wasp/releases for the list of valid versions, including the latest one.

    • wasp uninstall removes Wasp from your system.

      $ wasp uninstall

      🐝 --- Uninstalling Wasp ... ------------------------------------------------------

       We will remove the following directories:
         {home}/.local/share/wasp-lang/
         {home}/.cache/wasp/

       We will also remove the following files:
         {home}/.local/bin/wasp

       Are you sure you want to continue? [y/N]
       y

       ✅ --- Uninstalled Wasp -----------------------------------------------------------
    + + \ No newline at end of file diff --git a/docs/0.12.0/general/language.html b/docs/0.12.0/general/language.html index 5e5a5f6ed2..f1d70fe973 100644 --- a/docs/0.12.0/general/language.html +++ b/docs/0.12.0/general/language.html @@ -19,15 +19,15 @@ - - + + -
    -
    Version: 0.12.0

    Wasp Language (.wasp)

    Wasp language (what you write in .wasp files) is a declarative, statically typed, domain-specific language (DSL).

    It is a quite simple language, closer to JSON, CSS or SQL than to e.g. Javascript or Python, since it is not a general programming language, but more of a configuration language.

    It is pretty intuitive to learn (there isn't much to learn really!) and you can probably do just fine without reading this page and learning from the rest of the docs as you go, but if you want a bit more formal definition and deeper understanding of how it works, then read on!

    Declarations​

    The central point of Wasp language are declarations, and Wasp code is at the end just a bunch of declarations, each of them describing a part of your web app.

    app MyApp {
      title: "My app"
    }

    route RootRoute { path: "/", to: DashboardPage }

    page DashboardPage {
      component: import { DashboardPage } from "@src/Dashboard.jsx"
    }

    In the example above we described a web app via three declarations: app MyApp { ... }, route RootRoute { ... } and page DashboardPage { ... }.

    Syntax for writing a declaration is <declaration_type> <declaration_name> <declaration_body>, where:

    • <declaration_type> is one of the declaration types offered by Wasp (app, route, ...)
    • <declaration_name> is an identifier chosen by you to name this specific declaration
    • <declaration_body> is the value/definition of the declaration itself, which has to match the specific declaration body type expected by the chosen declaration type.

    So, for app declaration above, we have:

    • declaration type app
    • declaration name MyApp (we could have used any other identifier, like foobar, foo_bar, or hi3Ho)
    • declaration body { title: "My app" }, which is a dictionary with field title that has string value. +
      +
      Version: 0.12.0

      Wasp Language (.wasp)

      Wasp language (what you write in .wasp files) is a declarative, statically typed, domain-specific language (DSL).

      It is a quite simple language, closer to JSON, CSS or SQL than to e.g. Javascript or Python, since it is not a general programming language, but more of a configuration language.

      It is pretty intuitive to learn (there isn't much to learn really!) and you can probably do just fine without reading this page and learning from the rest of the docs as you go, but if you want a bit more formal definition and deeper understanding of how it works, then read on!

      Declarations​

      The central point of Wasp language are declarations, and Wasp code is at the end just a bunch of declarations, each of them describing a part of your web app.

      app MyApp {
        title: "My app"
      }

      route RootRoute { path: "/", to: DashboardPage }

      page DashboardPage {
        component: import { DashboardPage } from "@src/Dashboard.jsx"
      }

      In the example above we described a web app via three declarations: app MyApp { ... }, route RootRoute { ... } and page DashboardPage { ... }.

      Syntax for writing a declaration is <declaration_type> <declaration_name> <declaration_body>, where:

      • <declaration_type> is one of the declaration types offered by Wasp (app, route, ...)
      • <declaration_name> is an identifier chosen by you to name this specific declaration
      • <declaration_body> is the value/definition of the declaration itself, which has to match the specific declaration body type expected by the chosen declaration type.

      So, for app declaration above, we have:

      • declaration type app
      • declaration name MyApp (we could have used any other identifier, like foobar, foo_bar, or hi3Ho)
      • declaration body { title: "My app" }, which is a dictionary with field title that has string value. Type of this dictionary is in line with the declaration body type of the app declaration type. If we provided something else, e.g. changed title to little, we would get a type error from Wasp compiler since that does not match the expected type of the declaration body for app.

      Each declaration has a meaning behind it that describes how your web app should behave and function.

      All the other types in Wasp language (primitive types (string, number), composite types (dict, list), enum types (DbSystem), ...) are used to define the declaration bodies.

      Complete List of Wasp Types​

      Wasp's type system can be divided into two main categories of types: fundamental types and domain types.

      While fundamental types are here to be basic building blocks of a a language, and are very similar to what you would see in other popular languages, domain types are what makes Wasp special, as they model the concepts of a web app like page, route and similar.

      • Fundamental types (source of truth)
        • Primitive types
          • string ("foo", "they said: \"hi\"")
          • bool (true, false)
          • number (12, 14.5)
          • declaration reference (name of existing declaration: TaskPage, updateTask)
          • ExtImport (external import) (import Foo from "@src/bar.js", import { Smth } from "@src/a/b.js")
            • The path has to start with "@src". The rest is relative to the src directory.
            • Import has to be a default import import Foo or a single named import import { Foo }.
          • json ({=json { a: 5, b: ["hi"] } json=})
          • psl (Prisma Schema Language) ({=psl <psl data model syntax> psl=})
        • Composite types
          • dict (dictionary) ({ a: 5, b: "foo" })
          • list ([1, 2, 3])
          • tuple ((1, "bar"), (2, 4, true))
            • Tuples can be of size 2, 3 and 4.
      • Domain types (source of truth)
        • Declaration types
          • action
          • api
          • apiNamespace
          • app
          • entity
          • job
          • page
          • query
          • route
          • crud
        • Enum types
          • DbSystem
          • HttpMethod
          • JobExecutor
          • EmailProvider

      You can find more details about each of the domain types, both regarding their body types and what they mean, in the corresponding doc pages covering their features.

      - - + + \ No newline at end of file diff --git a/docs/0.12.0/migrate-from-0-11-to-0-12.html b/docs/0.12.0/migrate-from-0-11-to-0-12.html index 4d125ec3b0..0baa9af0a8 100644 --- a/docs/0.12.0/migrate-from-0-11-to-0-12.html +++ b/docs/0.12.0/migrate-from-0-11-to-0-12.html @@ -19,12 +19,12 @@ - - + + -
      -
      Version: 0.12.0

      Migration from 0.11.X to 0.12.X

      What's new in Wasp 0.12.0?​

      New project structure​

      Here's a file tree of a fresh Wasp project created with the previous version of Wasp. +

      +
      Version: 0.12.0

      Migration from 0.11.X to 0.12.X

      What's new in Wasp 0.12.0?​

      New project structure​

      Here's a file tree of a fresh Wasp project created with the previous version of Wasp. More precisely, this is what you'll get if you run wasp new myProject using Wasp 0.11.x:

      .
      ├── .gitignore
      ├── main.wasp
      ├── src
      │   ├── client
      │   │   ├── Main.css
      │   │   ├── MainPage.jsx
      │   │   ├── react-app-env.d.ts
      │   │   ├── tsconfig.json
      │   │   └── waspLogo.png
      │   ├── server
      │   │   └── tsconfig.json
      │   ├── shared
      │   │   └── tsconfig.json
      │   └── .waspignore
      └── .wasproot

      Compare that with the file tree of a fresh Wasp project created with Wasp 0.12.0. In other words, this is what you will get by running wasp new myProject from this point onwards:

      .
      ├── .gitignore
      ├── main.wasp
      ├── package.json
      ├── public
      │   └── .gitkeep
      ├── src
      │   ├── Main.css
      │   ├── MainPage.jsx
      │   ├── queries.ts
      │   ├── vite-env.d.ts
      │   ├── .waspignore
      │   └── waspLogo.png
      ├── tsconfig.json
      ├── vite.config.ts
      └── .wasproot

      The main differences are:

      • The server/client code separation is no longer necessary. You can now organize @@ -56,7 +56,7 @@ src/server), you are now free to reorganize your project however you think is best, as long as you keep all the source files in the src/ directory.

        This section is optional, but if you didn't like the server/client separation, now's the perfect time to change it.

        For example, if your src dir looked like this:

        src
        │
        ├── client
        │   ├── Dashboard.tsx
        │   ├── Login.tsx
        │   ├── MainPage.tsx
        │   ├── Register.tsx
        │   ├── Task.css
        │   ├── TaskLisk.tsx
        │   ├── Task.tsx
        │   └── User.tsx
        ├── server
        │   ├── taskActions.ts
        │   ├── taskQueries.ts
        │   ├── userActions.ts
        │   └── userQueries.ts
        └── shared
            └── utils.ts

        you can now change it to a feature-based structure (which we recommend for any project that is not very small):

        src
        │
        ├── task
        │   ├── actions.ts    -- former taskActions.ts
        │   ├── queries.ts    -- former taskQueries.ts
        │   ├── Task.css
        │   ├── TaskLisk.tsx
        │   └── Task.tsx
        ├── user
        │   ├── actions.ts    -- former userActions.ts
        │   ├── Dashboard.tsx
        │   ├── Login.tsx
        │   ├── queries.ts    -- former userQueries.ts
        │   ├── Register.tsx
        │   └── User.tsx
        ├── MainPage.tsx
        └── utils.ts

        Appendix​

        Example Data Migration Functions​

        The migration functions provided below are written with the typical use cases in mind and you can use them as-is. If your setup requires additional logic, you can use them as a good starting point and modify them to your needs.

        Note that all of the functions below are written to be idempotent, meaning that running a function multiple times can't hurt. This allows executing a function again in case only a part of the previous execution succeeded and also means that accidentally running it one time too much won't have any negative effects. We recommend you keep your data migration functions idempotent.

        Username & Password​

        To successfully migrate the users using the Username & Password auth method, you will need to do two things:

        1. Migrate the user data

          Username & Password data migration function
          main.wasp
          api migrateUsernameAndPassword {
            httpRoute: (GET, "/migrate-username-and-password"),
            fn: import { migrateUsernameAndPasswordHandler } from "@src/migrateToNewAuth",
            entities: []
          }
          src/migrateToNewAuth.ts
          import { prisma } from "wasp/server";
          import { type ProviderName, type UsernameProviderData } from "wasp/server/auth";
          import { MigrateUsernameAndPassword } from "wasp/server/api";

          export const migrateUsernameAndPasswordHandler: MigrateUsernameAndPassword =
            async (_req, res) => {
              const result = await migrateUsernameAuth();

              res.status(200).json({ message: "Migrated users to the new auth", result });
            };

          async function migrateUsernameAuth(): Promise<{
            numUsersAlreadyMigrated: number;
            numUsersNotUsingThisAuthMethod: number;
            numUsersMigratedSuccessfully: number;
          }> {
            const users = await prisma.user.findMany({
              include: {
                auth: true,
              },
            });

            const result = {
              numUsersAlreadyMigrated: 0,
              numUsersNotUsingThisAuthMethod: 0,
              numUsersMigratedSuccessfully: 0,
            };

            for (const user of users) {
              if (user.auth) {
                result.numUsersAlreadyMigrated++;
                console.log("Skipping user (already migrated) with id:", user.id);
                continue;
              }

              if (!user.username || !user.password) {
                result.numUsersNotUsingThisAuthMethod++;
                console.log("Skipping user (not using username auth) with id:", user.id);
                continue;
              }

              const providerData: UsernameProviderData = {
                hashedPassword: user.password,
              };
              const providerName: ProviderName = "username";

              await prisma.auth.create({
                data: {
                  identities: {
                    create: {
                      providerName,
                      providerUserId: user.username.toLowerCase(),
                      providerData: JSON.stringify(providerData),
                    },
                  },
                  user: {
                    connect: {
                      id: user.id,
                    },
                  },
                },
              });
              result.numUsersMigratedSuccessfully++;
            }

            return result;
          }

        2. Provide a way for users to migrate their password

          There is a breaking change between the old and the new auth in the way the password is hashed. This means that users will need to migrate their password after the migration, as the old password will no longer work.

          Since the only way users using username and password as a login method can verify their identity is by providing both their username and password (there is no email or any other info, unless you asked for it and stored it explicitly), we need to provide them a way to exchange their old password for a new password. One way to handle this is to inform them about the need to migrate their password (on the login page) and provide a custom page to migrate the password.

        Steps to create a custom page for migrating the password

        1. You will need to install the secure-password and sodium-native packages to use the old hashing algorithm:

          npm install secure-password@4.0.0 sodium-native@3.3.0 --save-exact

          Make sure to save the exact versions of the packages.

        2. Then you'll need to create a new page in your app where users can migrate their password. You can use the following code as a starting point:

        main.wasp
        route MigratePasswordRoute { path: "/migrate-password", to: MigratePassword }
        page MigratePassword {
          component: import { MigratePasswordPage } from "@src/pages/MigratePassword"
        }
        src/pages/MigratePassword.jsx
        import {
          FormItemGroup,
          FormLabel,
          FormInput,
          FormError,
        } from "wasp/client/auth";
        import { useForm } from "react-hook-form";
        import { migratePassword } from "wasp/client/operations";
        import { useState } from "react";

        export function MigratePasswordPage() {
          const [successMessage, setSuccessMessage] = useState(null);
          const [errorMessage, setErrorMessage] = useState(null);
          const form = useForm();

          const onSubmit = form.handleSubmit(async (data) => {
            try {
              const result = await migratePassword(data);
              setSuccessMessage(result.message);
            } catch (e) {
              console.error(e);
              if (e instanceof Error) {
                setErrorMessage(e.message);
              }
            }
          });

          return (
            <div style={{
              maxWidth: "400px",
              margin: "auto",
            }}>
              <h1>Migrate your password</h1>
              <p>
                If you have an account on the old version of the website, you can
                migrate your password to the new version.
              </p>
              {successMessage && <div>{successMessage}</div>}
              {errorMessage && <FormError>{errorMessage}</FormError>}
              <form onSubmit={onSubmit}>
                <FormItemGroup>
                  <FormLabel>Username</FormLabel>
                  <FormInput
                    {...form.register("username", {
                      required: "Username is required",
                    })}
                  />
                  <FormError>{form.formState.errors.username?.message}</FormError>
                </FormItemGroup>
                <FormItemGroup>
                  <FormLabel>Password</FormLabel>
                  <FormInput
                    {...form.register("password", {
                      required: "Password is required",
                    })}
                    type="password"
                  />
                  <FormError>{form.formState.errors.password?.message}</FormError>
                </FormItemGroup>
                <button type="submit">Migrate password</button>
              </form>
            </div>
          );
        }
        1. Finally, you will need to create a new operation in your app to handle the password migration. You can use the following code as a starting point:
        main.wasp
        action migratePassword {
          fn: import { migratePassword } from "@src/auth",
          entities: []
        }
        src/auth.js
        import SecurePassword from "secure-password";
        import { HttpError } from "wasp/server";
        import {
          createProviderId,
          deserializeAndSanitizeProviderData,
          findAuthIdentity,
          updateAuthIdentityProviderData,
        } from "wasp/server/auth";

        export const migratePassword = async ({ password, username }, _context) => {
          const providerId = createProviderId("username", username);
          const authIdentity = await findAuthIdentity(providerId);

          if (!authIdentity) {
            throw new HttpError(400, "Something went wrong");
          }

          const providerData = deserializeAndSanitizeProviderData(
            authIdentity.providerData
          );

          try {
            const SP = new SecurePassword();

            // This will verify the password using the old algorithm
            const result = await SP.verify(
              Buffer.from(password),
              Buffer.from(providerData.hashedPassword, "base64")
            );

            if (result !== SecurePassword.VALID) {
              throw new HttpError(400, "Something went wrong");
            }

            // This will hash the password using the new algorithm and update the
            // provider data in the database.
            await updateAuthIdentityProviderData(providerId, providerData, {
              hashedPassword: password,
            });
          } catch (e) {
            throw new HttpError(400, "Something went wrong");
          }

          return {
            message: "Password migrated successfully.",
          };
        };

        Email​

        To successfully migrate the users using the Email auth method, you will need to do two things:

        1. Migrate the user data

          Email data migration function
          main.wasp
          api migrateEmail {
            httpRoute: (GET, "/migrate-email"),
            fn: import { migrateEmailHandler } from "@src/migrateToNewAuth",
            entities: []
          }
          src/migrateToNewAuth.ts
          import { prisma } from "wasp/server";
          import { type ProviderName, type EmailProviderData } from "wasp/server/auth";
          import { MigrateEmail } from "wasp/server/api";

          export const migrateEmailHandler: MigrateEmail =
            async (_req, res) => {
              const result = await migrateEmailAuth();

              res.status(200).json({ message: "Migrated users to the new auth", result });
            };

          async function migrateEmailAuth(): Promise<{
            numUsersAlreadyMigrated: number;
            numUsersNotUsingThisAuthMethod: number;
            numUsersMigratedSuccessfully: number;
          }> {
            const users = await prisma.user.findMany({
              include: {
                auth: true,
              },
            });

            const result = {
              numUsersAlreadyMigrated: 0,
              numUsersNotUsingThisAuthMethod: 0,
              numUsersMigratedSuccessfully: 0,
            };

            for (const user of users) {
              if (user.auth) {
                result.numUsersAlreadyMigrated++;
                console.log("Skipping user (already migrated) with id:", user.id);
                continue;
              }

              if (!user.email || !user.password) {
                result.numUsersNotUsingThisAuthMethod++;
                console.log("Skipping user (not using email auth) with id:", user.id);
                continue;
              }

              const providerData: EmailProviderData = {
                isEmailVerified: user.isEmailVerified,
                emailVerificationSentAt:
                  user.emailVerificationSentAt?.toISOString() ?? null,
                passwordResetSentAt: user.passwordResetSentAt?.toISOString() ?? null,
                hashedPassword: user.password,
              };
              const providerName: ProviderName = "email";

              await prisma.auth.create({
                data: {
                  identities: {
                    create: {
                      providerName,
                      providerUserId: user.email,
                      providerData: JSON.stringify(providerData),
                    },
                  },
                  user: {
                    connect: {
                      id: user.id,
                    },
                  },
                },
              });
              result.numUsersMigratedSuccessfully++;
            }

            return result;
          }

        2. Ask the users to reset their password

          There is a breaking change between the old and the new auth in the way the password is hashed. This means that users will need to reset their password after the migration, as the old password will no longer work.

          It would be best to notify your users about this change and put a notice on your login page to request a password reset.

        Google & GitHub​

        Google & GitHub data migration functions
        main.wasp
        api migrateGoogle {
          httpRoute: (GET, "/migrate-google"),
          fn: import { migrateGoogleHandler } from "@src/migrateToNewAuth",
          entities: []
        }

        api migrateGithub {
          httpRoute: (GET, "/migrate-github"),
          fn: import { migrateGithubHandler } from "@src/migrateToNewAuth",
          entities: []
        }
        src/migrateToNewAuth.ts
        import { prisma } from "wasp/server";
        import { MigrateGoogle, MigrateGithub } from "wasp/server/api";

        export const migrateGoogleHandler: MigrateGoogle =
          async (_req, res) => {
            const result = await createSocialLoginMigration("google");

            res.status(200).json({ message: "Migrated users to the new auth", result });
          };

        export const migrateGithubHandler: MigrateGithub =
          async (_req, res) => {
            const result = await createSocialLoginMigration("github");

            res.status(200).json({ message: "Migrated users to the new auth", result });
          };

        async function createSocialLoginMigration(
          providerName: "google" | "github"
        ): Promise<{
          numUsersAlreadyMigrated: number;
          numUsersNotUsingThisAuthMethod: number;
          numUsersMigratedSuccessfully: number;
        }> {
          const users = await prisma.user.findMany({
            include: {
              auth: true,
              externalAuthAssociations: true,
            },
          });

          const result = {
            numUsersAlreadyMigrated: 0,
            numUsersNotUsingThisAuthMethod: 0,
            numUsersMigratedSuccessfully: 0,
          };

          for (const user of users) {
            if (user.auth) {
              result.numUsersAlreadyMigrated++;
              console.log("Skipping user (already migrated) with id:", user.id);
              continue;
            }

            const provider = user.externalAuthAssociations.find(
              (provider) => provider.provider === providerName
            );

            if (!provider) {
              result.numUsersNotUsingThisAuthMethod++;
              console.log(`Skipping user (not using ${providerName} auth) with id:`, user.id);
              continue;
            }

            await prisma.auth.create({
              data: {
                identities: {
                  create: {
                    providerName,
                    providerUserId: provider.providerId,
                    providerData: JSON.stringify({}),
                  },
                },
                user: {
                  connect: {
                    id: user.id,
                  },
                },
              },
            });
            result.numUsersMigratedSuccessfully++;
          }

          return result;
        }
      - - + + \ No newline at end of file diff --git a/docs/0.12.0/project/client-config.html b/docs/0.12.0/project/client-config.html index 20c682f25c..ee502ad4d4 100644 --- a/docs/0.12.0/project/client-config.html +++ b/docs/0.12.0/project/client-config.html @@ -19,12 +19,12 @@ - - + + -
      -
      Version: 0.12.0

      Client Config

      You can configure the client using the client field inside the app declaration:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
          setupFn: import mySetupFunction from "@src/myClientSetupCode.js"
        }
      }

      Root Component​

      Wasp gives you the option to define a "wrapper" component for your React app.

      It can be used for a variety of purposes, but the most common ones are:

      • Defining a common layout for your application.
      • Setting up various providers that your application needs.

      Defining a Common Layout​

      Let's define a common layout for your application:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
        }
      }
      src/Root.jsx
      export default function Root({ children }) {
        return (
          <div>
            <header>
              <h1>My App</h1>
            </header>
            {children}
            <footer>
              <p>My App footer</p>
            </footer>
          </div>
        )
      }

      Setting up a Provider​

      This is how to set up various providers that your application needs:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
        }
      }
      src/Root.jsx
      import store from './store'
      import { Provider } from 'react-redux'

      export default function Root({ children }) {
        return <Provider store={store}>{children}</Provider>
      }

      As long as you render the children, you can do whatever you want in your root +

      +
      Version: 0.12.0

      Client Config

      You can configure the client using the client field inside the app declaration:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
          setupFn: import mySetupFunction from "@src/myClientSetupCode.js"
        }
      }

      Root Component​

      Wasp gives you the option to define a "wrapper" component for your React app.

      It can be used for a variety of purposes, but the most common ones are:

      • Defining a common layout for your application.
      • Setting up various providers that your application needs.

      Defining a Common Layout​

      Let's define a common layout for your application:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
        }
      }
      src/Root.jsx
      export default function Root({ children }) {
        return (
          <div>
            <header>
              <h1>My App</h1>
            </header>
            {children}
            <footer>
              <p>My App footer</p>
            </footer>
          </div>
        )
      }

      Setting up a Provider​

      This is how to set up various providers that your application needs:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
        }
      }
      src/Root.jsx
      import store from './store'
      import { Provider } from 'react-redux'

      export default function Root({ children }) {
        return <Provider store={store}>{children}</Provider>
      }

      As long as you render the children, you can do whatever you want in your root component.

      Read more about the root component in the API Reference.

      Setup Function​

      setupFn declares a function that Wasp executes on the client before everything else.

      Running Some Code​

      We can run any code we want in the setup function.

      For example, here's a setup function that logs a message every hour:

      src/myClientSetupCode.js
      export default async function mySetupFunction() {
        let count = 1
        setInterval(
          () => console.log(`You have been online for ${count++} hours.`),
          1000 * 60 * 60
        )
      }

      Overriding Default Behaviour for Queries​

      info

      You can change the options for a single Query using the options object, as described here.

      Wasp's useQuery hook uses react-query's useQuery hook under the hood. Since react-query comes configured with aggressive but sane default options, you most likely won't have to change those defaults for all Queries.

      If you do need to change the global defaults, you can do so inside the client setup function.

      Wasp exposes a configureQueryClient hook that lets you configure react-query's QueryClient object:

      src/myClientSetupCode.js
      import { configureQueryClient } from 'wasp/client/operations'

      export default async function mySetupFunction() {
        // ... some setup
        configureQueryClient({
          defaultOptions: {
            queries: {
              staleTime: Infinity,
            },
          },
        })
        // ... some more setup
      }

      Make sure to pass in an object expected by the QueryClient's constructor, as explained in react-query's docs.

      Read more about the setup function in the API Reference.

      Base Directory​

      If you need to serve the client from a subdirectory, you can use the baseDir option:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          baseDir: "/my-app",
        }
      }

      This means that if you serve your app from https://example.com/my-app, the @@ -35,7 +35,7 @@ renders a custom layout:

      src/Root.jsx
      import store from './store'
      import { Provider } from 'react-redux'

      export default function Root({ children }) {
        return (
          <Provider store={store}>
            <Layout>{children}</Layout>
          </Provider>
        )
      }

      function Layout({ children }) {
        return (
          <div>
            <header>
              <h1>My App</h1>
            </header>
            {children}
            <footer>
              <p>My App footer</p>
            </footer>
          </div>
        )
      }

    • setupFn: ExtImport​

      You can use this function to perform any custom setup (e.g., setting up client-side periodic jobs).

      src/myClientSetupCode.js
      export default async function mySetupFunction() {
        // Run some code
      }

    • baseDir: String​

      If you need to serve the client from a subdirectory, you can use the baseDir option.

      If you set baseDir to /my-app for example, that will make Wasp set the basename prop of the Router to /my-app. It will also set the base option of the Vite config to /my-app.

      This means that if you serve your app from https://example.com/my-app, the router will work correctly, and all the assets will be served from https://example.com/my-app.

      Setting the correct env variable

      If you set the baseDir option, make sure that the WASP_WEB_CLIENT_URL env variable also includes that base directory.

      For example, if you are serving your app from https://example.com/my-app, the WASP_WEB_CLIENT_URL should be also set to https://example.com/my-app, and not just https://example.com.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/project/css-frameworks.html b/docs/0.12.0/project/css-frameworks.html index 813e4bb5fa..d005a957c2 100644 --- a/docs/0.12.0/project/css-frameworks.html +++ b/docs/0.12.0/project/css-frameworks.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.12.0

    CSS Frameworks

    Tailwind​

    To enable support for Tailwind in your project, you need to add two config files — tailwind.config.cjs and postcss.config.cjs — to the root directory.

    With these files present, Wasp installs the necessary dependencies and copies your configuration to the generated project. You can then use Tailwind CSS directives in your CSS and Tailwind classes on your React components.

    tree .
    .
    ├── main.wasp
    ├── package.json
    ├── src
    │   ├── Main.css
    │   ├── MainPage.jsx
    │   ├── vite-env.d.ts
    │   └── waspLogo.png
    ├── public
    ├── tsconfig.json
    ├── vite.config.ts
    ├── postcss.config.cjs
    └── tailwind.config.cjs
    Tailwind not working?

    If you can not use Tailwind after adding the required config files, make sure to restart wasp start. This is sometimes needed to ensure that Wasp picks up the changes and enables Tailwind integration.

    Enabling Tailwind Step-by-Step​

    caution

    Make sure to use the .cjs extension for these config files, if you name them with a .js extension, Wasp will not detect them.

    1. Add ./tailwind.config.cjs.

      ./tailwind.config.cjs
      const { resolveProjectPath } = require('wasp/dev')

      /** @type {import('tailwindcss').Config} */
      module.exports = {
        content: [resolveProjectPath('./src/**/*.{js,jsx,ts,tsx}')],
        theme: {
          extend: {},
        },
        plugins: [],
      }

    2. Add ./postcss.config.cjs.

      ./postcss.config.cjs
      module.exports = {
        plugins: {
          tailwindcss: {},
          autoprefixer: {},
        },
      }

    3. Import Tailwind into your CSS file. For example, in a new project you might import Tailwind into Main.css.

      ./src/Main.css
      @tailwind base;
      @tailwind components;
      @tailwind utilities;

      /* ... */

    4. Start using Tailwind 🥳

      ./src/MainPage.jsx
      // ...

      <h1 className="text-3xl font-bold underline">
        Hello world!
      </h1>

      // ...

    Adding Tailwind Plugins​

    To add Tailwind plugins, install them as npm development dependencies and add them to the plugins list in your tailwind.config.cjs file:

    npm install -D @tailwindcss/forms
    npm install -D @tailwindcss/typography

    and also

    ./tailwind.config.cjs
    /** @type {import('tailwindcss').Config} */
    module.exports = {
      // ...
      plugins: [
        require('@tailwindcss/forms'),
        require('@tailwindcss/typography'),
      ],
      // ...
    }
    - - +
    +
    Version: 0.12.0

    CSS Frameworks

    Tailwind​

    To enable support for Tailwind in your project, you need to add two config files — tailwind.config.cjs and postcss.config.cjs — to the root directory.

    With these files present, Wasp installs the necessary dependencies and copies your configuration to the generated project. You can then use Tailwind CSS directives in your CSS and Tailwind classes on your React components.

    tree .
    .
    ├── main.wasp
    ├── package.json
    ├── src
    │   ├── Main.css
    │   ├── MainPage.jsx
    │   ├── vite-env.d.ts
    │   └── waspLogo.png
    ├── public
    ├── tsconfig.json
    ├── vite.config.ts
    ├── postcss.config.cjs
    └── tailwind.config.cjs
    Tailwind not working?

    If you can not use Tailwind after adding the required config files, make sure to restart wasp start. This is sometimes needed to ensure that Wasp picks up the changes and enables Tailwind integration.

    Enabling Tailwind Step-by-Step​

    caution

    Make sure to use the .cjs extension for these config files, if you name them with a .js extension, Wasp will not detect them.

    1. Add ./tailwind.config.cjs.

      ./tailwind.config.cjs
      const { resolveProjectPath } = require('wasp/dev')

      /** @type {import('tailwindcss').Config} */
      module.exports = {
        content: [resolveProjectPath('./src/**/*.{js,jsx,ts,tsx}')],
        theme: {
          extend: {},
        },
        plugins: [],
      }

    2. Add ./postcss.config.cjs.

      ./postcss.config.cjs
      module.exports = {
        plugins: {
          tailwindcss: {},
          autoprefixer: {},
        },
      }

    3. Import Tailwind into your CSS file. For example, in a new project you might import Tailwind into Main.css.

      ./src/Main.css
      @tailwind base;
      @tailwind components;
      @tailwind utilities;

      /* ... */

    4. Start using Tailwind 🥳

      ./src/MainPage.jsx
      // ...

      <h1 className="text-3xl font-bold underline">
        Hello world!
      </h1>

      // ...

    Adding Tailwind Plugins​

    To add Tailwind plugins, install them as npm development dependencies and add them to the plugins list in your tailwind.config.cjs file:

    npm install -D @tailwindcss/forms
    npm install -D @tailwindcss/typography

    and also

    ./tailwind.config.cjs
    /** @type {import('tailwindcss').Config} */
    module.exports = {
      // ...
      plugins: [
        require('@tailwindcss/forms'),
        require('@tailwindcss/typography'),
      ],
      // ...
    }
    + + \ No newline at end of file diff --git a/docs/0.12.0/project/custom-vite-config.html b/docs/0.12.0/project/custom-vite-config.html index 1b907ebaac..be117da454 100644 --- a/docs/0.12.0/project/custom-vite-config.html +++ b/docs/0.12.0/project/custom-vite-config.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.12.0

    Custom Vite Config

    Wasp uses Vite to serve the client during development and bundling it for production. If you want to customize the Vite config, you can do that by editing the vite.config.ts file in your project root directory.

    Wasp will use your config and merge it with the default Wasp's Vite config.

    Vite config customization can be useful for things like:

    • Adding custom Vite plugins.
    • Customising the dev server.
    • Customising the build process.

    Be careful with making changes to the Vite config, as it can break the Wasp's client build process. Check out the default Vite config here to see what you can change.

    Examples​

    Below are some examples of how you can customize the Vite config.

    Changing the Dev Server Behaviour​

    If you want to stop Vite from opening the browser automatically when you run wasp start, you can do that by customizing the open option.

    vite.config.js
    export default {
      server: {
        open: false,
      },
    }

    Custom Dev Server Port​

    You have access to all of the Vite dev server options in your custom Vite config. You can change the dev server port by setting the port option.

    vite.config.js
    export default {
      server: {
        port: 4000,
      },
    }
    .env.server
    WASP_WEB_CLIENT_URL=http://localhost:4000
    Changing the dev server port

    ⚠️ Be careful when changing the dev server port, you'll need to update the WASP_WEB_CLIENT_URL env var in your .env.server file.

    Customising the Base Path​

    If you, for example, want to serve the client from a different path than /, you can do that by customizing the base option.

    vite.config.js
    export default {
      base: '/my-app/',
    }
    - - +
    +
    Version: 0.12.0

    Custom Vite Config

    Wasp uses Vite to serve the client during development and bundling it for production. If you want to customize the Vite config, you can do that by editing the vite.config.ts file in your project root directory.

    Wasp will use your config and merge it with the default Wasp's Vite config.

    Vite config customization can be useful for things like:

    • Adding custom Vite plugins.
    • Customising the dev server.
    • Customising the build process.

    Be careful with making changes to the Vite config, as it can break the Wasp's client build process. Check out the default Vite config here to see what you can change.

    Examples​

    Below are some examples of how you can customize the Vite config.

    Changing the Dev Server Behaviour​

    If you want to stop Vite from opening the browser automatically when you run wasp start, you can do that by customizing the open option.

    vite.config.js
    export default {
      server: {
        open: false,
      },
    }

    Custom Dev Server Port​

    You have access to all of the Vite dev server options in your custom Vite config. You can change the dev server port by setting the port option.

    vite.config.js
    export default {
      server: {
        port: 4000,
      },
    }
    .env.server
    WASP_WEB_CLIENT_URL=http://localhost:4000
    Changing the dev server port

    ⚠️ Be careful when changing the dev server port, you'll need to update the WASP_WEB_CLIENT_URL env var in your .env.server file.

    Customising the Base Path​

    If you, for example, want to serve the client from a different path than /, you can do that by customizing the base option.

    vite.config.js
    export default {
      base: '/my-app/',
    }
    + + \ No newline at end of file diff --git a/docs/0.12.0/project/customizing-app.html b/docs/0.12.0/project/customizing-app.html index 07c103fcfd..13e9b58324 100644 --- a/docs/0.12.0/project/customizing-app.html +++ b/docs/0.12.0/project/customizing-app.html @@ -19,14 +19,14 @@ - - + + -
    -
    Version: 0.12.0

    Customizing the App

    Each Wasp project can have only one app type declaration. It is used to configure your app and its components.

    app todoApp {
      wasp: {
        version: "^0.12.0"
      },
      title: "ToDo App",
      head: [
        "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto:300,400,500&display=swap\" />"
      ]
    }

    We'll go through some common customizations you might want to do to your app. For more details on each of the fields, check out the API Reference.

    Changing the App Title​

    You may want to change the title of your app, which appears in the browser tab, next to the favicon. You can change it by changing the title field of your app declaration:

    app myApp {
      wasp: {
        version: "^0.12.0"
      },
      title: "BookFace"
    }

    Adding Additional Lines to the Head​

    If you are looking to add additional style sheets or scripts to your app, you can do so by adding them to the head field of your app declaration.

    An example of adding extra style sheets and scripts:

    app myApp {
      wasp: {
        version: "^0.12.0"
      },
      title: "My App",
      head: [  // optional
        "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto:300,400,500&display=swap\" />",
        "<script src=\"https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.3/Chart.min.js\"></script>",
        "<meta name=\"viewport\" content=\"minimum-scale=1, initial-scale=1, width=device-width\" />"
      ]
    }

    API Reference​

    app todoApp {
      wasp: {
        version: "^0.12.0"
      },
      title: "ToDo App",
      head: [
        "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto:300,400,500&display=swap\" />"
      ],
      auth: {
        // ...
      },
      client: {
        // ...
      },
      server: {
        // ...
      },
      db: {
        // ...
      },
      emailSender: {
        // ...
      },
      webSocket: {
        // ...
      }
    }

    The app declaration has the following fields:

    Content and Communication​

    • Excellence comes from iteration. First drafts are always bad, but writing them is a vital part of the process. It's extremely difficult to avoid the slow progression of Bad -> OK -> Good -> Great -> Inspiring -> Transcendent.
    • Only wait until something is "Good" before publishing. Vue's guide originally says: "The community will help you push it further down the chain." We don't yet have that luxury, as our community isn't large enough. Still, we can't afford to invest too much time into the docs, so "Good" will have to do for now.

    Processes​

    • Ideally, you should write the docs before you implement the feature. This will help you see the feature from the user's perspective and better spot the API's deficiencies and improvement potential. If something is difficult to explain, it's most likely difficult to understand. If it is difficult to understand, there might be a better way of designing it.
    • Try not to get defensive when receiving feedback. Our writing can be very personal to us, but if we get upset with the people who help us improve it, they will either stop giving feedback or start limiting the kind of feedback they give.
    • Proofread your work before showing it to others (and use Grammarly). If you show someone work with many spelling/grammar mistakes, you'll get feedback about spelling grammar/mistakes instead of more valuable notes about whether the writing is achieving your goals.
    • When you ask people for feedback, tell reviewers:
      • What you're trying to do.
      • What your fears are.
      • Which balances you're trying to strike.
    • Do your best to come up with a good and straighforward way to say something. Again, this will help the reviewer focus on high-level issues instead of rephrasing your sentences.
    • Read and correct your text several times before submitting it (preferably with some time between the readings). This is similar to proofreading but has more to do with content and communication style than grammar. A time offset is beneficial because it removes the text from your short-term memory, helping you view it more objectively.
    • It's OK to ask AI to improve your text. Just make sure to check it and correct it. You should always sign off on the last version.
    • When someone reports a problem, there is almost always a problem, even if the solution they proposed isn't quite right. Keep asking follow-up questions to learn more.
    • People need to feel safe asking questions when contributing/reviewing content. Here's how you can do that:
      • Thank people for their contributions/reviews, even if you're feeling grumpy. For example:
        • "Great question!"
        • "Thanks for taking the time to explain. 🙂"
        • "This is actually intentional, but thanks for taking the time to contribute. 😊"
      • Listen to what people are saying and mirror if you're not sure you're understanding correctly. This can help validate people's feelings and experiences while also understanding if you're understanding them correctly.
      • Use a lot of positive and empathetic emojis. It's always better to seem a little strange than mean or impatient. This primarily applies to Wasp team members speaking to outside contributors. Since most of the core team knows each other pretty well, there's no need to go overboard with the emojis and pleasantries.
      • Kindly communicate rules/boundaries. If someone behaves in a way that's abusive/inappropriate, respond only with kindness and maturity, but also make it clear that this behavior is not acceptable and what will happen (according to the code of conduct) if they continue behaving poorly.
    • All docs must go through the review cycle, preferably with more than a single reviewer. Different people focus on different things. Some of us are great at coming up with examples, others easily come up with analogies and explain complex topics, some have a clear and concise writing style, etc. Therefore, try to get at least two or three people to review your document.

    Possible improvements​

    • Some parts of our docs don't follow all the guidelines outlined in this document. There's no need to start fixing all the issues right away. We can slowly improve the docs as we edit them.
    • We've discussed having a git repo with all the example code in the docs. This should make copying, pasting, testing, and maintaining code snippets easier.
    - - + + \ No newline at end of file diff --git a/docs/advanced/accessing-app-config.html b/docs/advanced/accessing-app-config.html index 4daa8d5b62..817b345ce0 100644 --- a/docs/advanced/accessing-app-config.html +++ b/docs/advanced/accessing-app-config.html @@ -19,12 +19,12 @@ - - + + -
    -
    Version: 0.13.0

    Accessing the configuration

    Whenever you start a Wasp app, you are starting two processes.

    Using an external auth method?

    If your app is using an external authentication method(s) supported by Wasp (such as Google or GitHub), make sure to additionally set the necessary environment variables specifically required by these method(s).

    While these are the general instructions on deploying the server anywhere, we also have more detailed instructions for chosen providers below, so check that out for more guidance if you are deploying to one of those providers.

    3. Deploying the Web Client (frontend)​

    To build the web app, position yourself in .wasp/build/web-app directory:

    cd .wasp/build/web-app

    Run

    npm install && REACT_APP_API_URL=<url_to_wasp_backend> npm run build

    where <url_to_wasp_backend> is the URL of the Wasp server that you previously deployed.

    The command above will build the web client and put it in the build/ directory in the web-app directory.

    Since the app's frontend is just a bunch of static files, you can deploy it to any static hosting provider.

    4. Deploying the Database​

    Any PostgreSQL database will do, as long as you provide the server with the correct DATABASE_URL env var and ensure that the database is accessible from the server.

    Different Providers​

    We'll cover a few different deployment providers below:

    • Fly.io (server and database)
    • Netlify (client)
    • Railway (server, client and database)
    • Heroku (server and database)

    Fly.io (server and database)​

    We will show how to deploy the server and provision a database for it on Fly.io.

    We automated this process for you

    If you want to do all of the work below with one command, you can use the Wasp CLI.

    Wasp CLI deploys the server, deploys the client, and sets up a database. It also gives you a way to redeploy (update) your app with a single command.

    Fly.io offers a variety of free services that are perfect for deploying your first Wasp app! You will need a Fly.io account and the flyctl CLI.

    note

    Fly.io offers support for both locally built Docker containers and remotely built ones. However, for simplicity and reproducibility, we will default to the use of a remote Fly.io builder.

    Additionally, fly is a symlink for flyctl on most systems and they can be used interchangeably.

    Make sure you are logged in with flyctl CLI. You can check if you are logged in with flyctl auth whoami, and if you are not, you can log in with flyctl auth login.

    Set Up a Fly.io App​

    info

    You need to do this only once per Wasp app.

    Unless you already have a Fly.io app that you want to deploy to, let's create a new Fly.io app.

    After you have built the app, position yourself in .wasp/build/ directory:

    cd .wasp/build

    Next, run the launch command to set up a new app and create a fly.toml file:

    flyctl launch --remote-only

    This will ask you a series of questions, such as asking you to choose a region and whether you'd like a database.

    • Say yes to Would you like to set up a PostgreSQL database now? and select Development. Fly.io will set a DATABASE_URL for you.

    • Say no to Would you like to deploy now? (and to any additional questions).

      We still need to set up several environment variables.

    What if the database setup fails?

    If your attempts to initiate a new app fail for whatever reason, then you should run flyctl apps destroy <app-name> before trying again. Fly does not allow you to create multiple apps with the same name.

    What does it look like when your DB is deployed correctly?

    When your DB is deployed correctly, you'll see it in the Fly.io dashboard:

    image

    Next, let's copy the fly.toml file up to our Wasp project dir for safekeeping.

    cp fly.toml ../../

    Next, let's add a few more environment variables:

    flyctl secrets set PORT=8080
    flyctl secrets set JWT_SECRET=<random_string_at_least_32_characters_long>
    flyctl secrets set WASP_WEB_CLIENT_URL=<url_of_where_client_will_be_deployed>
    flyctl secrets set WASP_SERVER_URL=<url_of_where_server_will_be_deployed>
    note

    If you do not know what your client URL is yet, don't worry. You can set WASP_WEB_CLIENT_URL after you deploy your client.

    Using an external auth method?

    If your app is using an external authentication method(s) supported by Wasp (such as Google or GitHub), make sure to additionally set the necessary environment variables specifically required by these method(s).

    If you want to make sure you've added your secrets correctly, run flyctl secrets list in the terminal. Note that you will see hashed versions of your secrets to protect your sensitive data.

    Deploy to a Fly.io App​

    While still in the .wasp/build/ directory, run:

    flyctl deploy --remote-only --config ../../fly.toml

    This will build and deploy the backend of your Wasp app on Fly.io to https://<app-name>.fly.dev 🤘🎸

    Now, if you haven't, you can deploy your client and add the client URL by running flyctl secrets set WASP_WEB_CLIENT_URL=<url_of_deployed_client>. We suggest using Netlify for your client, but you can use any static hosting provider.

    Additionally, some useful flyctl commands:

    flyctl logs
    flyctl secrets list
    flyctl ssh console

    Redeploying After Wasp Builds​

    When you rebuild your Wasp app (with wasp build), it will remove your .wasp/build/ directory. In there, you may have a fly.toml from any prior Fly.io deployments.

    While we will improve this process in the future, in the meantime, you have a few options:

    1. Copy the fly.toml file to a versioned directory, like your Wasp project dir.

      From there, you can reference it in flyctl deploy --config <path> commands, like above.

    2. Backup the fly.toml file somewhere before running wasp build, and copy it into .wasp/build/ after.

      When the fly.toml file exists in .wasp/build/ dir, you do not need to specify the --config <path>.

    3. Run flyctl config save -a <app-name> to regenerate the fly.toml file from the remote state stored in Fly.io.

    Netlify (client)​

    We'll show how to deploy the client on Netlify.

    Netlify is a static hosting solution that is free for many use cases. You will need a Netlify account and Netlify CLI installed to follow these instructions.

    Make sure you are logged in with Netlify CLI. You can check if you are logged in with netlify status, and if you are not, you can log in with netlify login.

    First, make sure you have built the Wasp app. We'll build the client web app next.

    To build the web app, position yourself in .wasp/build/web-app directory:

    cd .wasp/build/web-app

    Run

    npm install && REACT_APP_API_URL=<url_to_wasp_backend> npm run build

    where <url_to_wasp_backend> is the URL of the Wasp server that you previously deployed.

    We can now deploy the client with:

    netlify deploy

    Carefully follow the instructions i.e. do you want to create a new app or use an existing one, the team under which your app will reside etc.

    The final step is to run:

    netlify deploy --prod`

    That is it! Your client should be live at https://<app-name>.netlify.app ✨

    note

    Make sure you set this URL as the WASP_WEB_CLIENT_URL environment variable in your server hosting environment (e.g., Fly.io or Heroku).

    Railway (server, client and database)​

    We will show how to deploy the client, the server, and provision a database on Railway.

    Railway is a simple and great way to host your server and database. It's also possible to deploy your entire app: database, server, and client. You can use the platform for free for a limited time, or if you meet certain eligibility requirements. See their plans page for more info.

    Prerequisites​

    To get started, follow these steps:

    1. Make sure your Wasp app is built by running wasp build in the project dir.

    2. Create a Railway account

      Free Tier

      Sign up with your GitHub account to be eligible for the free tier

    3. Install the Railway CLI

    4. Run railway login and a browser tab will open to authenticate you.

    Create New Project​

    Let's create our Railway project:

    1. Go to your Railway dashboard, click on New Project, and select Provision PostgreSQL from the dropdown menu.
    2. Once it initializes, right-click on the New button in the top right corner and select Empty Service.
    3. Once it initializes, click on it, go to Settings > General and change the name to server
    4. Go ahead and create another empty service and name it client

    Changing the name

    Deploy Your App to Railway​

    Setup Domains​

    We'll need the domains for both the server and client services:

    1. Go to the server instance's Settings tab, and click Generate Domain.
    2. Do the same under the client's Settings.

    Copy the domains as we will need them later.

    Deploying the Server​

    Let's deploy our server first:

    1. Move into your app's .wasp/build/ directory:

      cd .wasp/build

    2. Link your app build to your newly created Railway project:

      railway link

    3. Go into the Railway dashboard and set up the required env variables:

      Open the Settings and go to the Variables tab:

      • click Variable reference and select DATABASE_URL (it will populate it with the correct value)

      • add WASP_WEB_CLIENT_URL - enter the client domain (e.g. https://client-production-XXXX.up.railway.app)

      • add WASP_SERVER_URL - enter the server domain (e.g. https://server-production-XXXX.up.railway.app)

      • add JWT_SECRET - enter a random string at least 32 characters long (use an online generator)

        Using an external auth method?

        If your app is using an external authentication method(s) supported by Wasp (such as Google or GitHub), make sure to additionally set the necessary environment variables specifically required by these method(s).

    4. Push and deploy the project:

    railway up

    Select server when prompted with Select Service.

    Railway will now locate the Dockerfile and deploy your server 👍

    Deploying the Client​

    1. Next, change into your app's frontend build directory .wasp/build/web-app:

      cd web-app

    2. Create the production build, using the server domain as the REACT_APP_API_URL:

      npm install && REACT_APP_API_URL=<url_to_wasp_backend> npm run build

    3. Next, we want to link this specific frontend directory to our project as well:

      railway link

    4. We need to configure Railway's static hosting for our client.

      Setting Up Static Hosting

      Copy the build folder within the web-app directory to dist:

      cp -r build dist

      We'll need to create the following files:

      • Dockerfile with:

        Dockerfile
        FROM pierrezemb/gostatic
        CMD [ "-fallback", "index.html" ]
        COPY ./dist/ /srv/http/

      • .dockerignore with:

        .dockerignore
        node_modules/

      You'll need to repeat these steps each time you run wasp build as it will remove the .wasp/build/web-app directory.

      Here's a useful shell script to do the process

      If you want to automate the process, save the following as deploy_client.sh in the root of your project:

      deploy_client.sh
      #!/usr/bin/env bash

      if [ -z "$REACT_APP_API_URL" ]
      then
        echo "REACT_APP_API_URL is not set"
        exit 1
      fi

      wasp build
      cd .wasp/build/web-app

      npm install && REACT_APP_API_URL=$REACT_APP_API_URL npm run build

      cp -r build dist

      dockerfile_contents=$(cat <<EOF
      FROM pierrezemb/gostatic
      CMD [ "-fallback", "index.html" ]
      COPY ./dist/ /srv/http/
      EOF
      )

      dockerignore_contents=$(cat <<EOF
      node_modules/
      EOF
      )

      echo "$dockerfile_contents" > Dockerfile
      echo "$dockerignore_contents" > .dockerignore

      railway up

      Make it executable with:

      chmod +x deploy_client.sh

      You can run it with:

      REACT_APP_API_URL=<url_to_wasp_backend> ./deploy_client.sh

    5. Set the PORT environment variable to 8043 under the Variables tab.

    6. Once set, deploy the client and select client when prompted with Select Service:

    railway up

    Conclusion​

    And now your Wasp should be deployed! 🐝 🚂 🚀

    Back in your Railway dashboard, click on your project and you should see your newly deployed services: PostgreSQL, Server, and Client.

    Updates & Redeploying​

    When you make updates and need to redeploy:

    • run wasp build to rebuild your app
    • run railway up in the .wasp/build directory (server)
    • repeat all the steps in the .wasp/build/web-app directory (client)

    Heroku (server and database)​

    We will show how to deploy the server and provision a database for it on Heroku.

    note

    Heroku used to offer free apps under certain limits. However, as of November 28, 2022, they ended support for their free tier. https://blog.heroku.com/next-chapter

    As such, we recommend using an alternative provider like Fly.io for your first apps.

    You will need Heroku account, heroku CLI and docker CLI installed to follow these instructions.

    Make sure you are logged in with heroku CLI. You can check if you are logged in with heroku whoami, and if you are not, you can log in with heroku login.

    Set Up a Heroku App​

    info

    You need to do this only once per Wasp app.

    Unless you want to deploy to an existing Heroku app, let's create a new Heroku app:

    heroku create <app-name>

    Unless you have an external PostgreSQL database that you want to use, let's create a new database on Heroku and attach it to our app:

    heroku addons:create --app <app-name> heroku-postgresql:mini
    caution

    Heroku does not offer a free plan anymore and mini is their cheapest database instance - it costs $5/mo.

    Heroku will also set DATABASE_URL env var for us at this point. If you are using an external database, you will have to set it up yourself.

    The PORT env var will also be provided by Heroku, so the ones left to set are the JWT_SECRET, WASP_WEB_CLIENT_URL and WASP_SERVER_URL env vars:

    heroku config:set --app <app-name> JWT_SECRET=<random_string_at_least_32_characters_long>
    heroku config:set --app <app-name> WASP_WEB_CLIENT_URL=<url_of_where_client_will_be_deployed>
    heroku config:set --app <app-name> WASP_SERVER_URL=<url_of_where_server_will_be_deployed>
    note

    If you do not know what your client URL is yet, don't worry. You can set WASP_WEB_CLIENT_URL after you deploy your client.

    Deploy to a Heroku App​

    After you have built the app, position yourself in .wasp/build/ directory:

    cd .wasp/build

    assuming you were at the root of your Wasp project at that moment.

    Log in to Heroku Container Registry:

    heroku container:login

    Build the docker image and push it to Heroku:

    heroku container:push --app <app-name> web

    App is still not deployed at this point. This step might take some time, especially the very first time, since there are no cached docker layers.

    Note for Apple Silicon Users

    Apple Silicon users need to build a non-Arm image, so the above step will not work at this time. Instead of heroku container:push, users instead should:

    docker buildx build --platform linux/amd64 -t <app-name> .
    docker tag <app-name> registry.heroku.com/<app-name>/web
    docker push registry.heroku.com/<app-name>/web

    You are now ready to proceed to the next step.

    Deploy the pushed image and restart the app:

    heroku container:release --app <app-name> web

    This is it, the backend is deployed at https://<app-name>-XXXX.herokuapp.com 🎉

    Find out the exact app URL with:

    heroku info --app <app-name>

    Additionally, you can check out the logs with:

    heroku logs --tail --app <app-name>
    Using pg-boss with Heroku

    If you wish to deploy an app leveraging Jobs that use pg-boss as the executor to Heroku, you need to set an additional environment variable called PG_BOSS_NEW_OPTIONS to {"connectionString":"<REGULAR_HEROKU_DATABASE_URL>","ssl":{"rejectUnauthorized":false}}. This is because pg-boss uses the pg extension, which does not seem to connect to Heroku over SSL by default, which Heroku requires. Additionally, Heroku uses a self-signed cert, so we must handle that as well.

    Read more: https://devcenter.heroku.com/articles/connecting-heroku-postgres#connecting-in-node-js

    Koyeb (server, client and database)​

    Check out the tutorial made by the team at Koyeb for detailed instructions on how to deploy a whole Wasp app on Koyeb: Using Wasp to Build Full-Stack Web Applications on Koyeb.

    The tutorial was written for Wasp v0.13.

    - - + + \ No newline at end of file diff --git a/docs/advanced/deployment/overview.html b/docs/advanced/deployment/overview.html index 63f422417b..02392ef3d0 100644 --- a/docs/advanced/deployment/overview.html +++ b/docs/advanced/deployment/overview.html @@ -19,17 +19,17 @@ - - + + -
    -
    Version: 0.13.0

    Overview

    Wasp apps are full-stack apps that consist of:

    • A Node.js server.
    • A static client.
    • A PostgreSQL database.

    You can deploy each part anywhere where you can usually deploy Node.js apps or static apps. For example, you can deploy your client on Netlify, the server on Fly.io, and the database on Neon.

    To make deploying as smooth as possible, Wasp also offers a single-command deployment through the Wasp CLI.

    Using Wasp CLI »

    One command deployment & redeployment

    Deploying Manually »

    Build the app and deploy it manually

    Click on each deployment method for more details.

    Regardless of how you choose to deploy your app (i.e., manually or using the Wasp CLI), you'll need to know about some common patterns covered below.

    Customizing the Dockerfile​

    By default, Wasp generates a multi-stage Dockerfile. +

    +
    Version: 0.13.0

    Overview

    Wasp apps are full-stack apps that consist of:

    • A Node.js server.
    • A static client.
    • A PostgreSQL database.

    You can deploy each part anywhere where you can usually deploy Node.js apps or static apps. For example, you can deploy your client on Netlify, the server on Fly.io, and the database on Neon.

    To make deploying as smooth as possible, Wasp also offers a single-command deployment through the Wasp CLI.

    Using Wasp CLI »

    One command deployment & redeployment

    Deploying Manually »

    Build the app and deploy it manually

    Click on each deployment method for more details.

    Regardless of how you choose to deploy your app (i.e., manually or using the Wasp CLI), you'll need to know about some common patterns covered below.

    Customizing the Dockerfile​

    By default, Wasp generates a multi-stage Dockerfile. This file is used to build and run a Docker image with the Wasp-generated server code. It also runs any pending migrations.

    You can add extra steps to this multi-stage Dockerfile by creating your own Dockerfile in the project's root directory. If Wasp finds a Dockerfile in the project's root, it appends its contents at the bottom of the default multi-stage Dockerfile.

    Since the last definition in a Dockerfile wins, you can override or continue from any existing build stages. You can also choose not to use any of our build stages and have your own custom Dockerfile used as-is.

    A few things to keep in mind:

    • If you override an intermediate build stage, no later build stages will be used unless you reproduce them below.
    • The generated Dockerfile's content is dynamic and depends on which features your app uses. The content can also change in future releases, so please verify it from time to time.
    • Make sure to supply ENTRYPOINT in your final build stage. Your changes won't have any effect if you don't.

    Read more in the official Docker docs on multi-stage builds.

    To see what your project's (potentially combined) Dockerfile will look like, run:

    wasp dockerfile

    Join our Discord if you have any questions, or if you need more customization than this hook provides.

    - - + + \ No newline at end of file diff --git a/docs/advanced/email.html b/docs/advanced/email.html index 2f2b6fe992..a341541821 100644 --- a/docs/advanced/email.html +++ b/docs/advanced/email.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Sending Emails

    With Wasp's email-sending feature, you can easily integrate email functionality into your web application.

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: <provider>,
        defaultFrom: {
          name: "Example",
          email: "hello@itsme.com"
        },
      }
    }

    Choose from one of the providers:

    • Dummy (development only),
    • Mailgun,
    • SendGrid
    • or the good old SMTP.

    Optionally, define the defaultFrom field, so you don't need to provide it whenever sending an email.

    Sending Emails​

    Before jumping into details about setting up various providers, let's see how easy it is to send emails.

    You import the emailSender that is provided by the wasp/server/email module and call the send method on it.

    src/actions/sendEmail.js
    import { emailSender } from "wasp/server/email";

    // In some action handler...
    const info = await emailSender.send({
      from: {
        name: "John Doe",
        email: "john@doe.com",
      },
      to: "user@domain.com",
      subject: "Saying hello",
      text: "Hello world",
      html: "Hello <strong>world</strong>",
    });

    Read more about the send method in the API Reference.

    The send method returns an object with the status of the sent email. It varies depending on the provider you use.

    Providers​

    We'll go over all of the available providers in the next section. For some of them, you'll need to set up some env variables. You can do that in the .env.server file.

    Using the Dummy Provider​

    Dummy Provider is not for production use

    The Dummy provider is not for production use. It is only meant to be used during development. If you try building your app with the Dummy provider, the build will fail.

    To speed up development, Wasp offers a Dummy email sender that console.logs the emails in the console. Since it doesn't send emails for real, it doesn't require any setup.

    Set the provider to Dummy in your main.wasp file.

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: Dummy,
      }
    }

    Using the SMTP Provider​

    First, set the provider to SMTP in your main.wasp file.

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: SMTP,
      }
    }

    Then, add the following env variables to your .env.server file.

    .env.server
    SMTP_HOST=
    SMTP_USERNAME=
    SMTP_PASSWORD=
    SMTP_PORT=

    Many transactional email providers (e.g. Mailgun, SendGrid but also others) can also use SMTP, so you can use them as well.

    Using the Mailgun Provider​

    Set the provider to Mailgun in the main.wasp file.

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: Mailgun,
      }
    }

    Then, get the Mailgun API key and domain and add them to your .env.server file.

    Getting the API Key and Domain​

    1. Go to Mailgun and create an account.
    2. Go to API Keys and create a new API key.
    3. Copy the API key and add it to your .env.server file.
    4. Go to Domains and create a new domain.
    5. Copy the domain and add it to your .env.server file.
    .env.server
    MAILGUN_API_KEY=
    MAILGUN_DOMAIN=

    Using the SendGrid Provider​

    Set the provider field to SendGrid in your main.wasp file.

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: SendGrid,
      }
    }

    Then, get the SendGrid API key and add it to your .env.server file.

    Getting the API Key​

    1. Go to SendGrid and create an account.
    2. Go to API Keys and create a new API key.
    3. Copy the API key and add it to your .env.server file.
    .env.server
    SENDGRID_API_KEY=

    API Reference​

    emailSender dict​

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: <provider>,
        defaultFrom: {
          name: "Example",
          email: "hello@itsme.com"
        },
      }
    }

    The emailSender dict has the following fields:

    • provider: Provider required

      The provider you want to use. Choose from Dummy, SMTP, Mailgun or SendGrid.

      Dummy Provider is not for production use

      The Dummy provider is not for production use. It is only meant to be used during development. If you try building your app with the Dummy provider, the build will fail.

    • defaultFrom: dict

      The default sender's details. If you set this field, you don't need to provide the from field when sending an email.

    JavaScript API​

    Using the emailSender in :

    src/actions/sendEmail.js
    import { emailSender } from "wasp/server/email";

    // In some action handler...
    const info = await emailSender.send({
      from: {
        name: "John Doe",
        email: "john@doe.com",
      },
      to: "user@domain.com",
      subject: "Saying hello",
      text: "Hello world",
      html: "Hello <strong>world</strong>",
    });

    The send method accepts an object with the following fields:

    • from: object

      The sender's details. If you set up defaultFrom field in the emailSender dict in Wasp file, this field is optional.

      • name: string

        The name of the sender.

      • email: string

        The email address of the sender.

    • to: string required

      The recipient's email address.

    • subject: string required

      The subject of the email.

    • text: string required

      The text version of the email.

    • html: string required

      The HTML version of the email

    - - +
    +
    Version: 0.13.0

    Sending Emails

    With Wasp's email-sending feature, you can easily integrate email functionality into your web application.

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: <provider>,
        defaultFrom: {
          name: "Example",
          email: "hello@itsme.com"
        },
      }
    }

    Choose from one of the providers:

    • Dummy (development only),
    • Mailgun,
    • SendGrid
    • or the good old SMTP.

    Optionally, define the defaultFrom field, so you don't need to provide it whenever sending an email.

    Sending Emails​

    Before jumping into details about setting up various providers, let's see how easy it is to send emails.

    You import the emailSender that is provided by the wasp/server/email module and call the send method on it.

    src/actions/sendEmail.js
    import { emailSender } from "wasp/server/email";

    // In some action handler...
    const info = await emailSender.send({
      from: {
        name: "John Doe",
        email: "john@doe.com",
      },
      to: "user@domain.com",
      subject: "Saying hello",
      text: "Hello world",
      html: "Hello <strong>world</strong>",
    });

    Read more about the send method in the API Reference.

    The send method returns an object with the status of the sent email. It varies depending on the provider you use.

    Providers​

    We'll go over all of the available providers in the next section. For some of them, you'll need to set up some env variables. You can do that in the .env.server file.

    Using the Dummy Provider​

    Dummy Provider is not for production use

    The Dummy provider is not for production use. It is only meant to be used during development. If you try building your app with the Dummy provider, the build will fail.

    To speed up development, Wasp offers a Dummy email sender that console.logs the emails in the console. Since it doesn't send emails for real, it doesn't require any setup.

    Set the provider to Dummy in your main.wasp file.

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: Dummy,
      }
    }

    Using the SMTP Provider​

    First, set the provider to SMTP in your main.wasp file.

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: SMTP,
      }
    }

    Then, add the following env variables to your .env.server file.

    .env.server
    SMTP_HOST=
    SMTP_USERNAME=
    SMTP_PASSWORD=
    SMTP_PORT=

    Many transactional email providers (e.g. Mailgun, SendGrid but also others) can also use SMTP, so you can use them as well.

    Using the Mailgun Provider​

    Set the provider to Mailgun in the main.wasp file.

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: Mailgun,
      }
    }

    Then, get the Mailgun API key and domain and add them to your .env.server file.

    Getting the API Key and Domain​

    1. Go to Mailgun and create an account.
    2. Go to API Keys and create a new API key.
    3. Copy the API key and add it to your .env.server file.
    4. Go to Domains and create a new domain.
    5. Copy the domain and add it to your .env.server file.
    .env.server
    MAILGUN_API_KEY=
    MAILGUN_DOMAIN=

    Using the SendGrid Provider​

    Set the provider field to SendGrid in your main.wasp file.

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: SendGrid,
      }
    }

    Then, get the SendGrid API key and add it to your .env.server file.

    Getting the API Key​

    1. Go to SendGrid and create an account.
    2. Go to API Keys and create a new API key.
    3. Copy the API key and add it to your .env.server file.
    .env.server
    SENDGRID_API_KEY=

    API Reference​

    emailSender dict​

    main.wasp
    app Example {
      ...
      emailSender: {
        provider: <provider>,
        defaultFrom: {
          name: "Example",
          email: "hello@itsme.com"
        },
      }
    }

    The emailSender dict has the following fields:

    • provider: Provider required

      The provider you want to use. Choose from Dummy, SMTP, Mailgun or SendGrid.

      Dummy Provider is not for production use

      The Dummy provider is not for production use. It is only meant to be used during development. If you try building your app with the Dummy provider, the build will fail.

    • defaultFrom: dict

      The default sender's details. If you set this field, you don't need to provide the from field when sending an email.

    JavaScript API​

    Using the emailSender in :

    src/actions/sendEmail.js
    import { emailSender } from "wasp/server/email";

    // In some action handler...
    const info = await emailSender.send({
      from: {
        name: "John Doe",
        email: "john@doe.com",
      },
      to: "user@domain.com",
      subject: "Saying hello",
      text: "Hello world",
      html: "Hello <strong>world</strong>",
    });

    The send method accepts an object with the following fields:

    • from: object

      The sender's details. If you set up defaultFrom field in the emailSender dict in Wasp file, this field is optional.

      • name: string

        The name of the sender.

      • email: string

        The email address of the sender.

    • to: string required

      The recipient's email address.

    • subject: string required

      The subject of the email.

    • text: string required

      The text version of the email.

    • html: string required

      The HTML version of the email

    + + \ No newline at end of file diff --git a/docs/advanced/jobs.html b/docs/advanced/jobs.html index 2cc60656d3..3061c62cec 100644 --- a/docs/advanced/jobs.html +++ b/docs/advanced/jobs.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Recurring Jobs

    In most web apps, users send requests to the server and receive responses with some data. When the server responds quickly, the app feels responsive and smooth.

    What if the server needs extra time to fully process the request? This might mean sending an email or making a slow HTTP request to an external API. In that case, it's a good idea to respond to the user as soon as possible and do the remaining work in the background.

    Wasp supports background jobs that can help you with this:

    • Jobs persist between server restarts,
    • Jobs can be retried if they fail,
    • Jobs can be delayed until a future time,
    • Jobs can have a recurring schedule.

    Using Jobs​

    Job Definition and Usage​

    Let's write an example Job that will print a message to the console and return a list of tasks from the database.

    1. Start by creating a Job declaration in your .wasp file:

      main.wasp
      job mySpecialJob {
        executor: PgBoss,
        perform: {
          fn: import { foo } from "@src/workers/bar"
        },
        entities: [Task],
      }

    2. After declaring the Job, implement its worker function:

      src/workers/bar.js
      export const foo = async ({ name }, context) => {
        console.log(`Hello ${name}!`)
        const tasks = await context.entities.Task.findMany({})
        return { tasks }
      }
      The worker function

      The worker function must be an async function. The function's return value represents the Job's result.

      The worker function accepts two arguments:

      • args: The data passed into the job when it's submitted.
      • context: { entities }: The context object containing entities you put in the Job declaration.

    3. After successfully defining the job, you can submit work to be done in your Operations or setupFn (or any other NodeJS code):

      someAction.js
      import { mySpecialJob } from 'wasp/server/jobs'

      const submittedJob = await mySpecialJob.submit({ job: "Johnny" })

      // Or, if you'd prefer it to execute in the future, just add a .delay().
      // It takes a number of seconds, Date, or ISO date string.
      await mySpecialJob
        .delay(10)
        .submit({ name: "Johnny" })

    And that's it. Your job will be executed by PgBoss as if you called foo({ name: "Johnny" }).

    In our example, foo takes an argument, but passing arguments to jobs is not a requirement. It depends on how you've implemented your worker function.

    Recurring Jobs​

    If you have work that needs to be done on some recurring basis, you can add a schedule to your job declaration:

    main.wasp
    job mySpecialJob {
      executor: PgBoss,
      perform: {
        fn: import { foo } from "@src/workers/bar"
      },
      schedule: {
        cron: "0 * * * *",
        args: {=json { "job": "args" } json=} // optional
      }
    }

    In this example, you don't need to invoke anything in . You can imagine foo({ job: "args" }) getting automatically scheduled and invoked for you every hour.

    API Reference​

    Declaring Jobs​

    main.wasp
    job mySpecialJob {
      executor: PgBoss,
      perform: {
        fn: import { foo } from "@src/workers/bar",
        executorOptions: {
          pgBoss: {=json { "retryLimit": 1 } json=}
        }
      },
      schedule: {
        cron: "*/5 * * * *",
        args: {=json { "foo": "bar" } json=},
        executorOptions: {
          pgBoss: {=json { "retryLimit": 0 } json=}
        }
      },
      entities: [Task],
    }

    The Job declaration has the following fields:

    • executor: JobExecutor required

      Job executors

      Our jobs need job executors to handle the scheduling, monitoring, and execution.

      PgBoss is currently our only job executor, and is recommended for low-volume production use cases. It requires your app.db.system to be PostgreSQL.

      We have selected pg-boss as our first job executor to handle the low-volume, basic job queue workloads many web applications have. By using PostgreSQL (and SKIP LOCKED) as its storage and synchronization mechanism, it allows us to provide many job queue pros without any additional infrastructure or complex management.

      info

      Keep in mind that pg-boss jobs run alongside your other server-side code, so they are not appropriate for CPU-heavy workloads. Additionally, some care is required if you modify scheduled jobs. Please see pg-boss details below for more information.

      pg-boss details

      pg-boss provides many useful features, which can be found here.

      When you add pg-boss to a Wasp project, it will automatically add a new schema to your database called pgboss with some internal tracking tables, including job and schedule. pg-boss tables have a name column in most tables that will correspond to your Job identifier. Additionally, these tables maintain arguments, states, return values, retry information, start and expiration times, and other metadata required by pg-boss.

      If you need to customize the creation of the pg-boss instance, you can set an environment variable called PG_BOSS_NEW_OPTIONS to a stringified JSON object containing these initialization parameters. NOTE: Setting this overwrites all Wasp defaults, so you must include database connection information as well.

      pg-boss considerations​

      • Wasp starts pg-boss alongside your web server's application, where both are simultaneously operational. This means that jobs running via pg-boss and the rest of the server logic (like Operations) share the CPU, therefore you should avoid running CPU-intensive tasks via jobs.
        • Wasp does not (yet) support independent, horizontal scaling of pg-boss-only applications, nor starting them as separate workers/processes/threads.
      • The job name/identifier in your .wasp file is the same name that will be used in the name column of pg-boss tables. If you change a name that had a schedule associated with it, pg-boss will continue scheduling those jobs but they will have no handlers associated, and will thus become stale and expire. To resolve this, you can remove the applicable row from the schedule table in the pgboss schema of your database.
        • If you remove a schedule from a job, you will need to do the above as well.
      • If you wish to deploy to Heroku, you need to set an additional environment variable called PG_BOSS_NEW_OPTIONS to {"connectionString":"<REGULAR_HEROKU_DATABASE_URL>","ssl":{"rejectUnauthorized":false}}. This is because pg-boss uses the pg extension, which does not seem to connect to Heroku over SSL by default, which Heroku requires. Additionally, Heroku uses a self-signed cert, so we must handle that as well.
      • https://devcenter.heroku.com/articles/connecting-heroku-postgres#connecting-in-node-js

    • perform: dict required

      • fn: ExtImport required

        • An async function that performs the work. Since Wasp executes Jobs on the server, the import path must lead to a NodeJS file.
        • It receives the following arguments:
          • args: Input: The data passed to the job when it's submitted.
          • context: { entities: Entities }: The context object containing any declared entities.

        Here's an example of a perform.fn function:

        src/workers/bar.js
        export const foo = async ({ name }, context) => {
          console.log(`Hello ${name}!`)
          const tasks = await context.entities.Task.findMany({})
          return { tasks }
        }

      • executorOptions: dict

        Executor-specific default options to use when submitting jobs. These are passed directly through and you should consult the documentation for the job executor. These can be overridden during invocation with submit() or in a schedule.

        • pgBoss: JSON

          See the docs for pg-boss.

    • schedule: dict

      • cron: string required

        A 5-placeholder format cron expression string. See rationale for minute-level precision here.

        If you need help building cron expressions, Check out Crontab guru.

      • args: JSON

        The arguments to pass to the perform.fn function when invoked.

      • executorOptions: dict

        Executor-specific options to use when submitting jobs. These are passed directly through and you should consult the documentation for the job executor. The perform.executorOptions are the default options, and schedule.executorOptions can override/extend those.

        • pgBoss: JSON

          See the docs for pg-boss.

    • entities: [Entity]

      A list of entities you wish to use inside your Job (similar to Queries and Actions).

    JavaScript API​

    • Importing a Job:

      someAction.js
      import { mySpecialJob } from 'wasp/server/jobs'

    • submit(jobArgs, executorOptions)

      • jobArgs: Input

      • executorOptions: object

        Submits a Job to be executed by an executor, optionally passing in a JSON job argument your job handler function receives, and executor-specific submit options.

      someAction.js
      const submittedJob = await mySpecialJob.submit({ job: "args" })

    • delay(startAfter)

      • startAfter: int | string | Date required

        Delaying the invocation of the job handler. The delay can be one of:

        • Integer: number of seconds to delay. [Default 0]
        • String: ISO date string to run at.
        • Date: Date to run at.
      someAction.js
      const submittedJob = await mySpecialJob
        .delay(10)
        .submit({ job: "args" }, { "retryLimit": 2 })

    Tracking​

    The return value of submit() is an instance of SubmittedJob, which has the following fields:

    • jobId: The ID for the job in that executor.
    • jobName: The name of the job you used in your .wasp file.
    • executorName: The Symbol of the name of the job executor.

    There are also some namespaced, job executor-specific objects.

    • For pg-boss, you may access: pgBoss
      • details(): pg-boss specific job detail information. Reference
      • cancel(): attempts to cancel a job. Reference
      • resume(): attempts to resume a canceled job. Reference
    - - +
    +
    Version: 0.13.0

    Recurring Jobs

    In most web apps, users send requests to the server and receive responses with some data. When the server responds quickly, the app feels responsive and smooth.

    What if the server needs extra time to fully process the request? This might mean sending an email or making a slow HTTP request to an external API. In that case, it's a good idea to respond to the user as soon as possible and do the remaining work in the background.

    Wasp supports background jobs that can help you with this:

    • Jobs persist between server restarts,
    • Jobs can be retried if they fail,
    • Jobs can be delayed until a future time,
    • Jobs can have a recurring schedule.

    Using Jobs​

    Job Definition and Usage​

    Let's write an example Job that will print a message to the console and return a list of tasks from the database.

    1. Start by creating a Job declaration in your .wasp file:

      main.wasp
      job mySpecialJob {
        executor: PgBoss,
        perform: {
          fn: import { foo } from "@src/workers/bar"
        },
        entities: [Task],
      }

    2. After declaring the Job, implement its worker function:

      src/workers/bar.js
      export const foo = async ({ name }, context) => {
        console.log(`Hello ${name}!`)
        const tasks = await context.entities.Task.findMany({})
        return { tasks }
      }
      The worker function

      The worker function must be an async function. The function's return value represents the Job's result.

      The worker function accepts two arguments:

      • args: The data passed into the job when it's submitted.
      • context: { entities }: The context object containing entities you put in the Job declaration.

    3. After successfully defining the job, you can submit work to be done in your Operations or setupFn (or any other NodeJS code):

      someAction.js
      import { mySpecialJob } from 'wasp/server/jobs'

      const submittedJob = await mySpecialJob.submit({ job: "Johnny" })

      // Or, if you'd prefer it to execute in the future, just add a .delay().
      // It takes a number of seconds, Date, or ISO date string.
      await mySpecialJob
        .delay(10)
        .submit({ name: "Johnny" })

    And that's it. Your job will be executed by PgBoss as if you called foo({ name: "Johnny" }).

    In our example, foo takes an argument, but passing arguments to jobs is not a requirement. It depends on how you've implemented your worker function.

    Recurring Jobs​

    If you have work that needs to be done on some recurring basis, you can add a schedule to your job declaration:

    main.wasp
    job mySpecialJob {
      executor: PgBoss,
      perform: {
        fn: import { foo } from "@src/workers/bar"
      },
      schedule: {
        cron: "0 * * * *",
        args: {=json { "job": "args" } json=} // optional
      }
    }

    In this example, you don't need to invoke anything in . You can imagine foo({ job: "args" }) getting automatically scheduled and invoked for you every hour.

    API Reference​

    Declaring Jobs​

    main.wasp
    job mySpecialJob {
      executor: PgBoss,
      perform: {
        fn: import { foo } from "@src/workers/bar",
        executorOptions: {
          pgBoss: {=json { "retryLimit": 1 } json=}
        }
      },
      schedule: {
        cron: "*/5 * * * *",
        args: {=json { "foo": "bar" } json=},
        executorOptions: {
          pgBoss: {=json { "retryLimit": 0 } json=}
        }
      },
      entities: [Task],
    }

    The Job declaration has the following fields:

    • executor: JobExecutor required

      Job executors

      Our jobs need job executors to handle the scheduling, monitoring, and execution.

      PgBoss is currently our only job executor, and is recommended for low-volume production use cases. It requires your app.db.system to be PostgreSQL.

      We have selected pg-boss as our first job executor to handle the low-volume, basic job queue workloads many web applications have. By using PostgreSQL (and SKIP LOCKED) as its storage and synchronization mechanism, it allows us to provide many job queue pros without any additional infrastructure or complex management.

      info

      Keep in mind that pg-boss jobs run alongside your other server-side code, so they are not appropriate for CPU-heavy workloads. Additionally, some care is required if you modify scheduled jobs. Please see pg-boss details below for more information.

      pg-boss details

      pg-boss provides many useful features, which can be found here.

      When you add pg-boss to a Wasp project, it will automatically add a new schema to your database called pgboss with some internal tracking tables, including job and schedule. pg-boss tables have a name column in most tables that will correspond to your Job identifier. Additionally, these tables maintain arguments, states, return values, retry information, start and expiration times, and other metadata required by pg-boss.

      If you need to customize the creation of the pg-boss instance, you can set an environment variable called PG_BOSS_NEW_OPTIONS to a stringified JSON object containing these initialization parameters. NOTE: Setting this overwrites all Wasp defaults, so you must include database connection information as well.

      pg-boss considerations​

      • Wasp starts pg-boss alongside your web server's application, where both are simultaneously operational. This means that jobs running via pg-boss and the rest of the server logic (like Operations) share the CPU, therefore you should avoid running CPU-intensive tasks via jobs.
        • Wasp does not (yet) support independent, horizontal scaling of pg-boss-only applications, nor starting them as separate workers/processes/threads.
      • The job name/identifier in your .wasp file is the same name that will be used in the name column of pg-boss tables. If you change a name that had a schedule associated with it, pg-boss will continue scheduling those jobs but they will have no handlers associated, and will thus become stale and expire. To resolve this, you can remove the applicable row from the schedule table in the pgboss schema of your database.
        • If you remove a schedule from a job, you will need to do the above as well.
      • If you wish to deploy to Heroku, you need to set an additional environment variable called PG_BOSS_NEW_OPTIONS to {"connectionString":"<REGULAR_HEROKU_DATABASE_URL>","ssl":{"rejectUnauthorized":false}}. This is because pg-boss uses the pg extension, which does not seem to connect to Heroku over SSL by default, which Heroku requires. Additionally, Heroku uses a self-signed cert, so we must handle that as well.
      • https://devcenter.heroku.com/articles/connecting-heroku-postgres#connecting-in-node-js

    • perform: dict required

      • fn: ExtImport required

        • An async function that performs the work. Since Wasp executes Jobs on the server, the import path must lead to a NodeJS file.
        • It receives the following arguments:
          • args: Input: The data passed to the job when it's submitted.
          • context: { entities: Entities }: The context object containing any declared entities.

        Here's an example of a perform.fn function:

        src/workers/bar.js
        export const foo = async ({ name }, context) => {
          console.log(`Hello ${name}!`)
          const tasks = await context.entities.Task.findMany({})
          return { tasks }
        }

      • executorOptions: dict

        Executor-specific default options to use when submitting jobs. These are passed directly through and you should consult the documentation for the job executor. These can be overridden during invocation with submit() or in a schedule.

        • pgBoss: JSON

          See the docs for pg-boss.

    • schedule: dict

      • cron: string required

        A 5-placeholder format cron expression string. See rationale for minute-level precision here.

        If you need help building cron expressions, Check out Crontab guru.

      • args: JSON

        The arguments to pass to the perform.fn function when invoked.

      • executorOptions: dict

        Executor-specific options to use when submitting jobs. These are passed directly through and you should consult the documentation for the job executor. The perform.executorOptions are the default options, and schedule.executorOptions can override/extend those.

        • pgBoss: JSON

          See the docs for pg-boss.

    • entities: [Entity]

      A list of entities you wish to use inside your Job (similar to Queries and Actions).

    JavaScript API​

    • Importing a Job:

      someAction.js
      import { mySpecialJob } from 'wasp/server/jobs'

    • submit(jobArgs, executorOptions)

      • jobArgs: Input

      • executorOptions: object

        Submits a Job to be executed by an executor, optionally passing in a JSON job argument your job handler function receives, and executor-specific submit options.

      someAction.js
      const submittedJob = await mySpecialJob.submit({ job: "args" })

    • delay(startAfter)

      • startAfter: int | string | Date required

        Delaying the invocation of the job handler. The delay can be one of:

        • Integer: number of seconds to delay. [Default 0]
        • String: ISO date string to run at.
        • Date: Date to run at.
      someAction.js
      const submittedJob = await mySpecialJob
        .delay(10)
        .submit({ job: "args" }, { "retryLimit": 2 })

    Tracking​

    The return value of submit() is an instance of SubmittedJob, which has the following fields:

    • jobId: The ID for the job in that executor.
    • jobName: The name of the job you used in your .wasp file.
    • executorName: The Symbol of the name of the job executor.

    There are also some namespaced, job executor-specific objects.

    • For pg-boss, you may access: pgBoss
      • details(): pg-boss specific job detail information. Reference
      • cancel(): attempts to cancel a job. Reference
      • resume(): attempts to resume a canceled job. Reference
    + + \ No newline at end of file diff --git a/docs/advanced/links.html b/docs/advanced/links.html index 820e1366ba..59da07aace 100644 --- a/docs/advanced/links.html +++ b/docs/advanced/links.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Type-Safe Links

    If you are using Typescript, you can use Wasp's custom Link component to create type-safe links to other pages on your site.

    After you defined a route:

    main.wasp
    route TaskRoute { path: "/task/:id", to: TaskPage }
    page TaskPage { ... }

    You can get the benefits of type-safe links by using the Link component from wasp/client/router:

    TaskList.tsx
    import { Link } from 'wasp/client/router'

    export const TaskList = () => {
      // ...

      return (
        <div>
          {tasks.map((task) => (
            <Link
              key={task.id}
              to="/task/:id"
              {/* 👆 You must provide a valid path here */}
              params={{ id: task.id }}>
              {/* 👆 All the params must be correctly passed in */}
              {task.description}
            </Link>
          ))}
        </div>
      )
    }

    Using Search Query & Hash​

    You can also pass search and hash props to the Link component:

    TaskList.tsx
    <Link
      to="/task/:id"
      params={{ id: task.id }}
      search={{ sortBy: 'date' }}
      hash="comments"
    >
      {task.description}
    </Link>

    This will result in a link like this: /task/1?sortBy=date#comments. Check out the API Reference for more details.

    The routes Object​

    You can also get all the pages in your app with the routes object:

    TaskList.tsx
    import { routes } from 'wasp/client/router'

    const linkToTask = routes.TaskRoute.build({ params: { id: 1 } })

    This will result in a link like this: /task/1.

    You can also pass search and hash props to the build function. Check out the API Reference for more details.

    API Reference​

    The Link component accepts the following props:

    • to required

      • A valid Wasp Route path from your main.wasp file.

    • params: { [name: string]: string | number } required (if the path contains params)

      • An object with keys and values for each param in the path.
      • For example, if the path is /task/:id, then the params prop must be { id: 1 }. Wasp supports required and optional params.

    • search: string[][] | Record<string, string> | string | URLSearchParams

      • Any valid input for URLSearchParams constructor.
      • For example, the object { sortBy: 'date' } becomes ?sortBy=date.

    • hash: string

    • all other props that the react-router-dom's Link component accepts

    routes Object​

    The routes object contains a function for each route in your app.

    router.tsx
    export const routes = {
      // RootRoute has a path like "/"
      RootRoute: {
        build: (options?: {
          search?: string[][] | Record<string, string> | string | URLSearchParams
          hash?: string
        }) => // ...
      },

      // DetailRoute has a path like "/task/:id/:something?"
      DetailRoute: {
        build: (
          options: {
            params: { id: ParamValue; something?: ParamValue; },
            search?: string[][] | Record<string, string> | string | URLSearchParams
            hash?: string
          }
        ) => // ...
      }
    }

    The params object is required if the route contains params. The search and hash parameters are optional.

    You can use the routes object like this:

    import { routes } from 'wasp/client/router'

    const linkToRoot = routes.RootRoute.build()
    const linkToTask = routes.DetailRoute.build({ params: { id: 1 } })
    - - +
    +
    Version: 0.13.0

    Type-Safe Links

    If you are using Typescript, you can use Wasp's custom Link component to create type-safe links to other pages on your site.

    After you defined a route:

    main.wasp
    route TaskRoute { path: "/task/:id", to: TaskPage }
    page TaskPage { ... }

    You can get the benefits of type-safe links by using the Link component from wasp/client/router:

    TaskList.tsx
    import { Link } from 'wasp/client/router'

    export const TaskList = () => {
      // ...

      return (
        <div>
          {tasks.map((task) => (
            <Link
              key={task.id}
              to="/task/:id"
              {/* 👆 You must provide a valid path here */}
              params={{ id: task.id }}>
              {/* 👆 All the params must be correctly passed in */}
              {task.description}
            </Link>
          ))}
        </div>
      )
    }

    Using Search Query & Hash​

    You can also pass search and hash props to the Link component:

    TaskList.tsx
    <Link
      to="/task/:id"
      params={{ id: task.id }}
      search={{ sortBy: 'date' }}
      hash="comments"
    >
      {task.description}
    </Link>

    This will result in a link like this: /task/1?sortBy=date#comments. Check out the API Reference for more details.

    The routes Object​

    You can also get all the pages in your app with the routes object:

    TaskList.tsx
    import { routes } from 'wasp/client/router'

    const linkToTask = routes.TaskRoute.build({ params: { id: 1 } })

    This will result in a link like this: /task/1.

    You can also pass search and hash props to the build function. Check out the API Reference for more details.

    API Reference​

    The Link component accepts the following props:

    • to required

      • A valid Wasp Route path from your main.wasp file.

    • params: { [name: string]: string | number } required (if the path contains params)

      • An object with keys and values for each param in the path.
      • For example, if the path is /task/:id, then the params prop must be { id: 1 }. Wasp supports required and optional params.

    • search: string[][] | Record<string, string> | string | URLSearchParams

      • Any valid input for URLSearchParams constructor.
      • For example, the object { sortBy: 'date' } becomes ?sortBy=date.

    • hash: string

    • all other props that the react-router-dom's Link component accepts

    routes Object​

    The routes object contains a function for each route in your app.

    router.tsx
    export const routes = {
      // RootRoute has a path like "/"
      RootRoute: {
        build: (options?: {
          search?: string[][] | Record<string, string> | string | URLSearchParams
          hash?: string
        }) => // ...
      },

      // DetailRoute has a path like "/task/:id/:something?"
      DetailRoute: {
        build: (
          options: {
            params: { id: ParamValue; something?: ParamValue; },
            search?: string[][] | Record<string, string> | string | URLSearchParams
            hash?: string
          }
        ) => // ...
      }
    }

    The params object is required if the route contains params. The search and hash parameters are optional.

    You can use the routes object like this:

    import { routes } from 'wasp/client/router'

    const linkToRoot = routes.RootRoute.build()
    const linkToTask = routes.DetailRoute.build({ params: { id: 1 } })
    + + \ No newline at end of file diff --git a/docs/advanced/middleware-config.html b/docs/advanced/middleware-config.html index 6c2914d69b..9104aeaf1a 100644 --- a/docs/advanced/middleware-config.html +++ b/docs/advanced/middleware-config.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Configuring Middleware

    Wasp comes with a minimal set of useful Express middleware in every application. While this is good for most users, we realize some may wish to add, modify, or remove some of these choices both globally, or on a per-api/path basis.

    Default Global Middleware 🌍​

    Wasp's Express server has the following middleware by default:

    • Helmet: Helmet helps you secure your Express apps by setting various HTTP headers. It's not a silver bullet, but it's a good start.

    • CORS: CORS is a package for providing a middleware that can be used to enable CORS with various options.

      note

      CORS middleware is required for the frontend to communicate with the backend.

    • Morgan: HTTP request logger middleware.

    • express.json (which uses body-parser): parses incoming request bodies in a middleware before your handlers, making the result available under the req.body property.

      note

      JSON middleware is required for Operations to function properly.

    • express.urlencoded (which uses body-parser): returns middleware that only parses urlencoded bodies and only looks at requests where the Content-Type header matches the type option.

    • cookieParser: parses Cookie header and populates req.cookies with an object keyed by the cookie names.

    Customization​

    You have three places where you can customize middleware:

    1. global: here, any changes will apply by default to all operations (query and action) and api. This is helpful if you wanted to add support for multiple domains to CORS, for example.

      Modifying global middleware

      Please treat modifications to global middleware with extreme care as they will affect all operations and APIs. If you are unsure, use one of the other two options.

    2. per-api: you can override middleware for a specific api route (e.g. POST /webhook/callback). This is helpful if you want to disable JSON parsing for some callback, for example.

    3. per-path: this is helpful if you need to customize middleware for all methods under a given path.

      • It's helpful for things like "complex CORS requests" which may need to apply to both OPTIONS and GET, or to apply some middleware to a set of api routes.

    Default Middleware Definitions​

    Below is the actual definitions of default middleware which you can override.

    const defaultGlobalMiddleware = new Map([
      ['helmet', helmet()],
      ['cors', cors({ origin: config.allowedCORSOrigins })],
      ['logger', logger('dev')],
      ['express.json', express.json()],
      ['express.urlencoded', express.urlencoded({ extended: false })],
      ['cookieParser', cookieParser()]
    ])

    1. Customize Global Middleware​

    If you would like to modify the middleware for all operations and APIs, you can do something like:

    main.wasp
    app todoApp {
      // ...

      server: {
        setupFn: import setup from "@src/serverSetup",
        middlewareConfigFn: import { serverMiddlewareFn } from "@src/serverSetup"
      },
    }
    src/serverSetup.js
    import cors from 'cors'
    import { config } from 'wasp/server'

    export const serverMiddlewareFn = (middlewareConfig) => {
      // Example of adding extra domains to CORS.
      middlewareConfig.set('cors', cors({ origin: [config.frontendUrl, 'https://example1.com', 'https://example2.com'] }))
      return middlewareConfig
    }

    2. Customize api-specific Middleware​

    If you would like to modify the middleware for a single API, you can do something like:

    main.wasp
    // ...

    api webhookCallback {
      fn: import { webhookCallback } from "@src/apis",
      middlewareConfigFn: import { webhookCallbackMiddlewareFn } from "@src/apis",
      httpRoute: (POST, "/webhook/callback"),
      auth: false
    }
    src/apis.js
    import express from 'express'

    export const webhookCallback = (req, res, _context) => {
      res.json({ msg: req.body.length })
    }

    export const webhookCallbackMiddlewareFn = (middlewareConfig) => {
      console.log('webhookCallbackMiddlewareFn: Swap express.json for express.raw')

      middlewareConfig.delete('express.json')
      middlewareConfig.set('express.raw', express.raw({ type: '*/*' }))

      return middlewareConfig
    }

    note

    This gets installed on a per-method basis. Behind the scenes, this results in code like:

    router.post('/webhook/callback', webhookCallbackMiddleware, ...)

    3. Customize Per-Path Middleware​

    If you would like to modify the middleware for all API routes under some common path, you can define a middlewareConfigFn on an apiNamespace:

    main.wasp
    // ...

    apiNamespace fooBar {
      middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@src/apis",
      path: "/foo/bar"
    }
    src/apis.js
    export const fooBarNamespaceMiddlewareFn = (middlewareConfig) => {
      const customMiddleware = (_req, _res, next) => {
        console.log('fooBarNamespaceMiddlewareFn: custom middleware')
        next()
      }

      middlewareConfig.set('custom.middleware', customMiddleware)

      return middlewareConfig
    }
    note

    This gets installed at the router level for the path. Behind the scenes, this results in something like:

    router.use('/foo/bar', fooBarNamespaceMiddleware)
    - - +
    +
    Version: 0.13.0

    Configuring Middleware

    Wasp comes with a minimal set of useful Express middleware in every application. While this is good for most users, we realize some may wish to add, modify, or remove some of these choices both globally, or on a per-api/path basis.

    Default Global Middleware 🌍​

    Wasp's Express server has the following middleware by default:

    • Helmet: Helmet helps you secure your Express apps by setting various HTTP headers. It's not a silver bullet, but it's a good start.

    • CORS: CORS is a package for providing a middleware that can be used to enable CORS with various options.

      note

      CORS middleware is required for the frontend to communicate with the backend.

    • Morgan: HTTP request logger middleware.

    • express.json (which uses body-parser): parses incoming request bodies in a middleware before your handlers, making the result available under the req.body property.

      note

      JSON middleware is required for Operations to function properly.

    • express.urlencoded (which uses body-parser): returns middleware that only parses urlencoded bodies and only looks at requests where the Content-Type header matches the type option.

    • cookieParser: parses Cookie header and populates req.cookies with an object keyed by the cookie names.

    Customization​

    You have three places where you can customize middleware:

    1. global: here, any changes will apply by default to all operations (query and action) and api. This is helpful if you wanted to add support for multiple domains to CORS, for example.

      Modifying global middleware

      Please treat modifications to global middleware with extreme care as they will affect all operations and APIs. If you are unsure, use one of the other two options.

    2. per-api: you can override middleware for a specific api route (e.g. POST /webhook/callback). This is helpful if you want to disable JSON parsing for some callback, for example.

    3. per-path: this is helpful if you need to customize middleware for all methods under a given path.

      • It's helpful for things like "complex CORS requests" which may need to apply to both OPTIONS and GET, or to apply some middleware to a set of api routes.

    Default Middleware Definitions​

    Below is the actual definitions of default middleware which you can override.

    const defaultGlobalMiddleware = new Map([
      ['helmet', helmet()],
      ['cors', cors({ origin: config.allowedCORSOrigins })],
      ['logger', logger('dev')],
      ['express.json', express.json()],
      ['express.urlencoded', express.urlencoded({ extended: false })],
      ['cookieParser', cookieParser()]
    ])

    1. Customize Global Middleware​

    If you would like to modify the middleware for all operations and APIs, you can do something like:

    main.wasp
    app todoApp {
      // ...

      server: {
        setupFn: import setup from "@src/serverSetup",
        middlewareConfigFn: import { serverMiddlewareFn } from "@src/serverSetup"
      },
    }
    src/serverSetup.js
    import cors from 'cors'
    import { config } from 'wasp/server'

    export const serverMiddlewareFn = (middlewareConfig) => {
      // Example of adding extra domains to CORS.
      middlewareConfig.set('cors', cors({ origin: [config.frontendUrl, 'https://example1.com', 'https://example2.com'] }))
      return middlewareConfig
    }

    2. Customize api-specific Middleware​

    If you would like to modify the middleware for a single API, you can do something like:

    main.wasp
    // ...

    api webhookCallback {
      fn: import { webhookCallback } from "@src/apis",
      middlewareConfigFn: import { webhookCallbackMiddlewareFn } from "@src/apis",
      httpRoute: (POST, "/webhook/callback"),
      auth: false
    }
    src/apis.js
    import express from 'express'

    export const webhookCallback = (req, res, _context) => {
      res.json({ msg: req.body.length })
    }

    export const webhookCallbackMiddlewareFn = (middlewareConfig) => {
      console.log('webhookCallbackMiddlewareFn: Swap express.json for express.raw')

      middlewareConfig.delete('express.json')
      middlewareConfig.set('express.raw', express.raw({ type: '*/*' }))

      return middlewareConfig
    }

    note

    This gets installed on a per-method basis. Behind the scenes, this results in code like:

    router.post('/webhook/callback', webhookCallbackMiddleware, ...)

    3. Customize Per-Path Middleware​

    If you would like to modify the middleware for all API routes under some common path, you can define a middlewareConfigFn on an apiNamespace:

    main.wasp
    // ...

    apiNamespace fooBar {
      middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@src/apis",
      path: "/foo/bar"
    }
    src/apis.js
    export const fooBarNamespaceMiddlewareFn = (middlewareConfig) => {
      const customMiddleware = (_req, _res, next) => {
        console.log('fooBarNamespaceMiddlewareFn: custom middleware')
        next()
      }

      middlewareConfig.set('custom.middleware', customMiddleware)

      return middlewareConfig
    }
    note

    This gets installed at the router level for the path. Behind the scenes, this results in something like:

    router.use('/foo/bar', fooBarNamespaceMiddleware)
    + + \ No newline at end of file diff --git a/docs/advanced/web-sockets.html b/docs/advanced/web-sockets.html index c9d4af6ad5..3210f64208 100644 --- a/docs/advanced/web-sockets.html +++ b/docs/advanced/web-sockets.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Web Sockets

    Wasp provides a fully integrated WebSocket experience by utilizing Socket.IO on the client and server.

    We handle making sure your URLs are correctly setup, CORS is enabled, and provide a useful useSocket and useSocketListener abstractions for use in React components.

    To get started, you need to:

    1. Define your WebSocket logic on the server.
    2. Enable WebSockets in your Wasp file, and connect it with your server logic.
    3. Use WebSockets on the client, in React, via useSocket and useSocketListener.
    4. Optionally, type the WebSocket events and payloads for full-stack type safety.

    Let's go through setting up WebSockets step by step, starting with enabling WebSockets in your Wasp file.

    Turn On WebSockets in Your Wasp File​

    We specify that we are using WebSockets by adding webSocket to our app and providing the required fn. You can optionally change the auto-connect behavior.

    todoApp.wasp
    app todoApp {
      // ...

      webSocket: {
        fn: import { webSocketFn } from "@src/webSocket",
        autoConnect: true, // optional, default: true
      },
    }

    Defining the Events Handler​

    Let's define the WebSockets server with all of the events and handler functions.

    webSocketFn Function​

    On the server, you will get Socket.IO io: Server argument and context for your WebSocket function. The context object give you access to all of the entities from your Wasp app.

    You can use this io object to register callbacks for all the regular Socket.IO events. Also, if a user is logged in, you will have a socket.data.user on the server.

    This is how we can define our webSocketFn function:

    src/webSocket.js
    import { v4 as uuidv4 } from 'uuid'
    import { getFirstProviderUserId } from 'wasp/auth'

    export const webSocketFn = (io, context) => {
      io.on('connection', (socket) => {
        const username = getFirstProviderUserId(socket.data.user) ?? 'Unknown'
        console.log('a user connected: ', username)

        socket.on('chatMessage', async (msg) => {
          console.log('message: ', msg)
          io.emit('chatMessage', { id: uuidv4(), username, text: msg })
          // You can also use your entities here:
          // await context.entities.SomeEntity.create({ someField: msg })
        })
      })
    }

    Using the WebSocket On The Client​

    useSocket Hook​

    Client access to WebSockets is provided by the useSocket hook. It returns:

    • socket: Socket for sending and receiving events.
    • isConnected: boolean for showing a display of the Socket.IO connection status.
      • Note: Wasp automatically connects and establishes a WebSocket connection from the client to the server by default, so you do not need to explicitly socket.connect() or socket.disconnect().
      • If you set autoConnect: false in your Wasp file, then you should call these as needed.

    All components using useSocket share the same underlying socket.

    useSocketListener Hook​

    Additionally, there is a useSocketListener: (event, callback) => void hook which is used for registering event handlers. It takes care of unregistering the handler on unmount.

    src/ChatPage.jsx
    import React, { useState } from 'react'
    import {
      useSocket,
      useSocketListener,
    } from 'wasp/client/webSocket'

    export const ChatPage = () => {
      const [messageText, setMessageText] = useState('')
      const [messages, setMessages] = useState([])
      const { socket, isConnected } = useSocket()

      useSocketListener('chatMessage', logMessage)

      function logMessage(msg) {
        setMessages((priorMessages) => [msg, ...priorMessages])
      }

      function handleSubmit(e) {
        e.preventDefault()
        socket.emit('chatMessage', messageText)
        setMessageText('')
      }

      const messageList = messages.map((msg) => (
        <li key={msg.id}>
          <em>{msg.username}</em>: {msg.text}
        </li>
      ))
      const connectionIcon = isConnected ? '🟢' : '🔴'

      return (
        <>
          <h2>Chat {connectionIcon}</h2>
          <div>
            <form onSubmit={handleSubmit}>
              <div>
                <div>
                  <input
                    type="text"
                    value={messageText}
                    onChange={(e) => setMessageText(e.target.value)}
                  />
                </div>
                <div>
                  <button type="submit">Submit</button>
                </div>
              </div>
            </form>
            <ul>{messageList}</ul>
          </div>
        </>
      )
    }

    API Reference​

    todoApp.wasp
    app todoApp {
      // ...

      webSocket: {
        fn: import { webSocketFn } from "@src/webSocket",
        autoConnect: true, // optional, default: true
      },
    }

    The webSocket dict has the following fields:

    • fn: WebSocketFn required

      The function that defines the WebSocket events and handlers.

    • autoConnect: bool

      Whether to automatically connect to the WebSocket server. Default: true.

    - - +
    +
    Version: 0.13.0

    Web Sockets

    Wasp provides a fully integrated WebSocket experience by utilizing Socket.IO on the client and server.

    We handle making sure your URLs are correctly setup, CORS is enabled, and provide a useful useSocket and useSocketListener abstractions for use in React components.

    To get started, you need to:

    1. Define your WebSocket logic on the server.
    2. Enable WebSockets in your Wasp file, and connect it with your server logic.
    3. Use WebSockets on the client, in React, via useSocket and useSocketListener.
    4. Optionally, type the WebSocket events and payloads for full-stack type safety.

    Let's go through setting up WebSockets step by step, starting with enabling WebSockets in your Wasp file.

    Turn On WebSockets in Your Wasp File​

    We specify that we are using WebSockets by adding webSocket to our app and providing the required fn. You can optionally change the auto-connect behavior.

    todoApp.wasp
    app todoApp {
      // ...

      webSocket: {
        fn: import { webSocketFn } from "@src/webSocket",
        autoConnect: true, // optional, default: true
      },
    }

    Defining the Events Handler​

    Let's define the WebSockets server with all of the events and handler functions.

    webSocketFn Function​

    On the server, you will get Socket.IO io: Server argument and context for your WebSocket function. The context object give you access to all of the entities from your Wasp app.

    You can use this io object to register callbacks for all the regular Socket.IO events. Also, if a user is logged in, you will have a socket.data.user on the server.

    This is how we can define our webSocketFn function:

    src/webSocket.js
    import { v4 as uuidv4 } from 'uuid'
    import { getFirstProviderUserId } from 'wasp/auth'

    export const webSocketFn = (io, context) => {
      io.on('connection', (socket) => {
        const username = getFirstProviderUserId(socket.data.user) ?? 'Unknown'
        console.log('a user connected: ', username)

        socket.on('chatMessage', async (msg) => {
          console.log('message: ', msg)
          io.emit('chatMessage', { id: uuidv4(), username, text: msg })
          // You can also use your entities here:
          // await context.entities.SomeEntity.create({ someField: msg })
        })
      })
    }

    Using the WebSocket On The Client​

    useSocket Hook​

    Client access to WebSockets is provided by the useSocket hook. It returns:

    • socket: Socket for sending and receiving events.
    • isConnected: boolean for showing a display of the Socket.IO connection status.
      • Note: Wasp automatically connects and establishes a WebSocket connection from the client to the server by default, so you do not need to explicitly socket.connect() or socket.disconnect().
      • If you set autoConnect: false in your Wasp file, then you should call these as needed.

    All components using useSocket share the same underlying socket.

    useSocketListener Hook​

    Additionally, there is a useSocketListener: (event, callback) => void hook which is used for registering event handlers. It takes care of unregistering the handler on unmount.

    src/ChatPage.jsx
    import React, { useState } from 'react'
    import {
      useSocket,
      useSocketListener,
    } from 'wasp/client/webSocket'

    export const ChatPage = () => {
      const [messageText, setMessageText] = useState('')
      const [messages, setMessages] = useState([])
      const { socket, isConnected } = useSocket()

      useSocketListener('chatMessage', logMessage)

      function logMessage(msg) {
        setMessages((priorMessages) => [msg, ...priorMessages])
      }

      function handleSubmit(e) {
        e.preventDefault()
        socket.emit('chatMessage', messageText)
        setMessageText('')
      }

      const messageList = messages.map((msg) => (
        <li key={msg.id}>
          <em>{msg.username}</em>: {msg.text}
        </li>
      ))
      const connectionIcon = isConnected ? '🟢' : '🔴'

      return (
        <>
          <h2>Chat {connectionIcon}</h2>
          <div>
            <form onSubmit={handleSubmit}>
              <div>
                <div>
                  <input
                    type="text"
                    value={messageText}
                    onChange={(e) => setMessageText(e.target.value)}
                  />
                </div>
                <div>
                  <button type="submit">Submit</button>
                </div>
              </div>
            </form>
            <ul>{messageList}</ul>
          </div>
        </>
      )
    }

    API Reference​

    todoApp.wasp
    app todoApp {
      // ...

      webSocket: {
        fn: import { webSocketFn } from "@src/webSocket",
        autoConnect: true, // optional, default: true
      },
    }

    The webSocket dict has the following fields:

    • fn: WebSocketFn required

      The function that defines the WebSocket events and handlers.

    • autoConnect: bool

      Whether to automatically connect to the WebSocket server. Default: true.

    + + \ No newline at end of file diff --git a/docs/auth/email.html b/docs/auth/email.html index abc6c65ac2..7741706984 100644 --- a/docs/auth/email.html +++ b/docs/auth/email.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Email

    Wasp supports e-mail authentication out of the box, along with email verification and "forgot your password?" flows. It provides you with the server-side implementation and email templates for all of these flows.

    Auth UI

    Using multiple auth identities for a single user

    Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

    Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

    Setting Up Email Authentication​

    We'll need to take the following steps to set up email authentication:

    1. Enable email authentication in the Wasp file
    2. Add the User entity
    3. Add the auth routes and pages
    4. Use Auth UI components in our pages
    5. Set up the email sender

    Structure of the main.wasp file we will end up with:

    main.wasp
    // Configuring e-mail authentication
    app myApp {
      auth: { ... }
    }

    // Defining User entity
    entity User { ... }

    // Defining routes and pages
    route SignupRoute { ... }
    page SignupPage { ... }
    // ...

    1. Enable Email Authentication in main.wasp​

    Let's start with adding the following to our main.wasp file:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the user entity (we'll define it next)
        userEntity: User,
        methods: {
          // 2. Enable email authentication
          email: {
            // 3. Specify the email from field
            fromField: {
              name: "My App Postman",
              email: "hello@itsme.com"
            },
            // 4. Specify the email verification and password reset options (we'll talk about them later)
            emailVerification: {
              clientRoute: EmailVerificationRoute,
            },
            passwordReset: {
              clientRoute: PasswordResetRoute,
            },
          },
        },
        onAuthFailedRedirectTo: "/login",
        onAuthSucceededRedirectTo: "/"
      },
    }

    Read more about the email auth method options here.

    2. Add the User Entity​

    The User entity can be as simple as including only the id field:

    main.wasp
    // 5. Define the user entity
    entity User {=psl
        id                        Int           @id @default(autoincrement())
        // Add your own fields below
        // ...
    psl=}

    You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

    3. Add the Routes and Pages​

    Next, we need to define the routes and pages for the authentication pages.

    Add the following to the main.wasp file:

    main.wasp
    // ...

    // 6. Define the routes
    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { Login } from "@src/pages/auth.jsx"
    }

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { Signup } from "@src/pages/auth.jsx"
    }

    route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
    page RequestPasswordResetPage {
      component: import { RequestPasswordReset } from "@src/pages/auth.jsx",
    }

    route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
    page PasswordResetPage {
      component: import { PasswordReset } from "@src/pages/auth.jsx",
    }

    route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
    page EmailVerificationPage {
      component: import { EmailVerification } from "@src/pages/auth.jsx",
    }

    We'll define the React components for these pages in the src/pages/auth.tsx file below.

    4. Create the Client Pages​

    info

    We are using Tailwind CSS to style the pages. Read more about how to add it here.

    Let's create a auth.tsx file in the src/pages folder and add the following to it:

    src/pages/auth.jsx
    import {
      LoginForm,
      SignupForm,
      VerifyEmailForm,
      ForgotPasswordForm,
      ResetPasswordForm,
    } from 'wasp/client/auth'
    import { Link } from 'react-router-dom'

    export function Login() {
      return (
        <Layout>
          <LoginForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            Don't have an account yet? <Link to="/signup">go to signup</Link>.
          </span>
          <br />
          <span className="text-sm font-medium text-gray-900">
            Forgot your password? <Link to="/request-password-reset">reset it</Link>
            .
          </span>
        </Layout>
      );
    }

    export function Signup() {
      return (
        <Layout>
          <SignupForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            I already have an account (<Link to="/login">go to login</Link>).
          </span>
        </Layout>
      );
    }

    export function EmailVerification() {
      return (
        <Layout>
          <VerifyEmailForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            If everything is okay, <Link to="/login">go to login</Link>
          </span>
        </Layout>
      );
    }

    export function RequestPasswordReset() {
      return (
        <Layout>
          <ForgotPasswordForm />
        </Layout>
      );
    }

    export function PasswordReset() {
      return (
        <Layout>
          <ResetPasswordForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            If everything is okay, <Link to="/login">go to login</Link>
          </span>
        </Layout>
      );
    }

    // A layout component to center the content
    export function Layout({ children }) {
      return (
        <div className="w-full h-full bg-white">
          <div className="min-w-full min-h-[75vh] flex items-center justify-center">
            <div className="w-full h-full max-w-sm p-5 bg-white">
              <div>{children}</div>
            </div>
          </div>
        </div>
      );
    }

    We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

    5. Set up an Email Sender​

    To support e-mail verification and password reset flows, we need an e-mail sender. Luckily, Wasp supports several email providers out of the box.

    We'll use the Dummy provider to speed up the setup. It just logs the emails to the console instead of sending them. You can use any of the supported email providers.

    To set up the Dummy provider to send emails, add the following to the main.wasp file:

    main.wasp
    app myApp {
      // ...
      // 7. Set up the email sender
      emailSender: {
        provider: Dummy,
      }
    }

    Conclusion​

    That's it! We have set up email authentication in our app. 🎉

    Running wasp db migrate-dev and then wasp start should give you a working app with email authentication. If you want to put some of the pages behind authentication, read the auth overview.

    Login and Signup Flows​

    Login​

    Auth UI

    Signup​

    Auth UI

    Some of the behavior you get out of the box:

    1. Rate limiting

      We are limiting the rate of sign-up requests to 1 request per minute per email address. This is done to prevent spamming.

    2. Preventing user email leaks

      If somebody tries to signup with an email that already exists and it's verified, we pretend that the account was created instead of saying it's an existing account. This is done to prevent leaking the user's email address.

    3. Allowing registration for unverified emails

      If a user tries to register with an existing but unverified email, we'll allow them to do that. This is done to prevent bad actors from locking out other users from registering with their email address.

    4. Password validation

      Read more about the default password validation rules and how to override them in auth overview docs.

    Email Verification Flow​

    Automatic email verification in development

    In development mode, you can skip the email verification step by setting the SKIP_EMAIL_VERIFICATION_IN_DEV environment variable to true in your .env.server file:

    .env.server
    SKIP_EMAIL_VERIFICATION_IN_DEV=true

    This is useful when you are developing your app and don't want to go through the email verification flow every time you sign up. It can be also useful when you are writing automated tests for your app.

    By default, Wasp requires the e-mail to be verified before allowing the user to log in. This is done by sending a verification email to the user's email address and requiring the user to click on a link in the email to verify their email address.

    Our setup looks like this:

    main.wasp
    // ...

    emailVerification: {
        clientRoute: EmailVerificationRoute,
    }

    When the user receives an e-mail, they receive a link that goes to the client route specified in the clientRoute field. In our case, this is the EmailVerificationRoute route we defined in the main.wasp file.

    The content of the e-mail can be customized, read more about it here.

    Email Verification Page​

    We defined our email verification page in the auth.tsx file.

    Auth UI

    Password Reset Flow​

    Users can request a password and then they'll receive an e-mail with a link to reset their password.

    Some of the behavior you get out of the box:

    1. Rate limiting

      We are limiting the rate of sign-up requests to 1 request per minute per email address. This is done to prevent spamming.

    2. Preventing user email leaks

      If somebody requests a password reset with an unknown email address, we'll give back the same response as if the user requested a password reset successfully. This is done to prevent leaking information.

    Our setup in main.wasp looks like this:

    main.wasp
    // ...

    passwordReset: {
        clientRoute: PasswordResetRoute,
    }

    Request Password Reset Page​

    Users request their password to be reset by going to the /request-password-reset route. We defined our request password reset page in the auth.tsx file.

    Request password reset page

    Password Reset Page​

    When the user receives an e-mail, they receive a link that goes to the client route specified in the clientRoute field. In our case, this is the PasswordResetRoute route we defined in the main.wasp file.

    Request password reset page

    Users can enter their new password there.

    The content of the e-mail can be customized, read more about it here.

    Creating a Custom Sign-up Action​

    Creating a custom sign-up action

    We don't recommend creating a custom sign-up action unless you have a good reason to do so. It is a complex process and you can easily make a mistake that will compromise the security of your app.

    The code of your custom sign-up action can look like this:

    main.wasp
    // ...

    action customSignup {
      fn: import { signup } from "@src/auth/signup.js",
    }
    src/auth/signup.js
    import {
      ensurePasswordIsPresent,
      ensureValidPassword,
      ensureValidEmail,
      createProviderId,
      sanitizeAndSerializeProviderData,
      deserializeAndSanitizeProviderData,
      findAuthIdentity,
      createUser,
      createEmailVerificationLink,
      sendEmailVerificationEmail,
    } from 'wasp/server/auth'

    export const signup = async (args, _context) => {
      ensureValidEmail(args)
      ensurePasswordIsPresent(args)
      ensureValidPassword(args)

      try {
        const providerId = createProviderId('email', args.email)
        const existingAuthIdentity = await findAuthIdentity(providerId)

        if (existingAuthIdentity) {
          const providerData = deserializeAndSanitizeProviderData(existingAuthIdentity.providerData)
          // Your custom code here
        } else {
          // sanitizeAndSerializeProviderData will hash the user's password
          const newUserProviderData = await sanitizeAndSerializeProviderData({
              hashedPassword: args.password,
              isEmailVerified: false,
              emailVerificationSentAt: null,
              passwordResetSentAt: null,
          })
          await createUser(
            providerId,
            providerData,
            // Any additional data you want to store on the User entity
            {},
          )

          // Verification link links to a client route e.g. /email-verification
          const verificationLink = await createEmailVerificationLink(args.email, '/email-verification');
          try {
              await sendEmailVerificationEmail(
                  args.email,
                  {
                      from: {
                        name: "My App Postman",
                        email: "hello@itsme.com",
                      },
                      to: args.email,
                      subject: "Verify your email",
                      text: `Click the link below to verify your email: ${verificationLink}`,
                      html: `
                          <p>Click the link below to verify your email</p>
                          <a href="${verificationLink}">Verify email</a>
                      `,
                  }
              );
          } catch (e: unknown) {
              console.error("Failed to send email verification email:", e);
              throw new HttpError(500, "Failed to send email verification email.");
          } 
        }
      } catch (e) {
        return {
          success: false,
          message: e.message,
        }
      }

      // Your custom code after sign-up.
      // ...

      return {
        success: true,
        message: 'User created successfully',
      }
    }

    We suggest using the built-in field validators for your authentication flow. You can import them from wasp/server/auth. These are the same validators that Wasp uses internally for the default authentication flow.

    Email​

    • ensureValidEmail(args)

      Checks if the email is valid and throws an error if it's not. Read more about the validation rules here.

    Password​

    • ensurePasswordIsPresent(args)

      Checks if the password is present and throws an error if it's not.

    • ensureValidPassword(args)

      Checks if the password is valid and throws an error if it's not. Read more about the validation rules here.

    Using Auth​

    To read more about how to set up the logout button and how to get access to the logged-in user in our client and server code, read the auth overview docs.

    getEmail​

    If you are looking to access the user's email in your code, you can do that by accessing the info about the user that is stored in the user.auth.identities array.

    To make things a bit easier for you, Wasp offers the getEmail helper.

    The getEmail helper returns the user's email or null if the user doesn't have an email auth identity.

    src/MainPage.jsx
    import { getEmail } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const email = getEmail(user)
      // ...
    }
    src/tasks.js
    import { getEmail } from 'wasp/auth'

    export const createTask = async (args, context) => {
      const email = getEmail(context.user)
      // ...
    }

    API Reference​

    Let's go over the options we can specify when using email authentication.

    userEntity fields​

    main.wasp
    app myApp {
      title: "My app",
      // ...

      auth: {
        userEntity: User,
        methods: {
          email: {
            // We'll explain these options below
          },
        },
        onAuthFailedRedirectTo: "/someRoute"
      },
      // ...
    }

    entity User {=psl
        id                        Int           @id @default(autoincrement())
    psl=}

    The user entity needs to have the following fields:

    • id required

      It can be of any type, but it needs to be marked with @id

    You can add any other fields you want to the user entity. Make sure to also define them in the userSignupFields field if they need to be set during the sign-up process.

    Fields in the email dict​

    main.wasp
    app myApp {
      title: "My app",
      // ...

      auth: {
        userEntity: User,
        methods: {
          email: {
            userSignupFields: import { userSignupFields } from "@src/auth.js",
            fromField: {
              name: "My App",
              email: "hello@itsme.com"
            },
            emailVerification: {
              clientRoute: EmailVerificationRoute,
              getEmailContentFn: import { getVerificationEmailContent } from "@src/auth/email.js",
            },
            passwordReset: {
              clientRoute: PasswordResetRoute,
              getEmailContentFn: import { getPasswordResetEmailContent } from "@src/auth/email.js",
            },
          },
        },
        onAuthFailedRedirectTo: "/someRoute"
      },
      // ...
    }

    userSignupFields: ExtImport​

    userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

    src/auth.js
    import { defineUserSignupFields } from 'wasp/server/auth'

    export const userSignupFields = defineUserSignupFields({
      address: (data) => {
        if (!data.address) {
          throw new Error('Address is required')
        }
        return data.address
      }
      phone: (data) => data.phone,
    })
    Read more about the `userSignupFields` function [here](./overview#1-defining-extra-fields).

    fromField: EmailFromField required​

    fromField is a dict that specifies the name and e-mail address of the sender of the e-mails sent by your app.

    It has the following fields:

    • name: name of the sender
    • email: e-mail address of the sender required

    emailVerification: EmailVerificationConfig required​

    emailVerification is a dict that specifies the details of the e-mail verification process.

    It has the following fields:

    • clientRoute: Route: a route that is used for the user to verify their e-mail address. required

      Client route should handle the process of taking a token from the URL and sending it to the server to verify the e-mail address. You can use our verifyEmail action for that.

      src/pages/EmailVerificationPage.jsx
      import { verifyEmail } from 'wasp/client/auth'
      ...
      await verifyEmail({ token });
      note

      We used Auth UI above to avoid doing this work of sending the token to the server manually.

    • getEmailContentFn: ExtImport: a function that returns the content of the e-mail that is sent to the user.

      Defining getEmailContentFn can be done by defining a file in the src directory.

      src/email.js
      export const getVerificationEmailContent = ({ verificationLink }) => ({
        subject: 'Verify your email',
        text: `Click the link below to verify your email: ${verificationLink}`,
        html: `
              <p>Click the link below to verify your email</p>
              <a href="${verificationLink}">Verify email</a>
          `,
      })
      This is the default content of the e-mail, you can customize it to your liking.

    passwordReset: PasswordResetConfig required​

    passwordReset is a dict that specifies the password reset process.

    It has the following fields:

    • clientRoute: Route: a route that is used for the user to reset their password. required

      Client route should handle the process of taking a token from the URL and a new password from the user and sending it to the server. You can use our requestPasswordReset and resetPassword actions to do that.

      src/pages/ForgotPasswordPage.jsx
      import { requestPasswordReset } from 'wasp/client/auth'
      ...
      await requestPasswordReset({ email });
      src/pages/PasswordResetPage.jsx
      import { resetPassword } from 'wasp/client/auth'
      ...
      await resetPassword({ password, token })
      note

      We used Auth UI above to avoid doing this work of sending the password request and the new password to the server manually.

    • getEmailContentFn: ExtImport: a function that returns the content of the e-mail that is sent to the user.

      Defining getEmailContentFn is done by defining a function that looks like this:

      src/email.js
      export const getPasswordResetEmailContent = ({ passwordResetLink }) => ({
        subject: 'Password reset',
        text: `Click the link below to reset your password: ${passwordResetLink}`,
        html: `
              <p>Click the link below to reset your password</p>
              <a href="${passwordResetLink}">Reset password</a>
          `,
      })
      This is the default content of the e-mail, you can customize it to your liking.
    - - +
    +
    Version: 0.13.0

    Email

    Wasp supports e-mail authentication out of the box, along with email verification and "forgot your password?" flows. It provides you with the server-side implementation and email templates for all of these flows.

    Auth UI

    Using multiple auth identities for a single user

    Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

    Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

    Setting Up Email Authentication​

    We'll need to take the following steps to set up email authentication:

    1. Enable email authentication in the Wasp file
    2. Add the User entity
    3. Add the auth routes and pages
    4. Use Auth UI components in our pages
    5. Set up the email sender

    Structure of the main.wasp file we will end up with:

    main.wasp
    // Configuring e-mail authentication
    app myApp {
      auth: { ... }
    }

    // Defining User entity
    entity User { ... }

    // Defining routes and pages
    route SignupRoute { ... }
    page SignupPage { ... }
    // ...

    1. Enable Email Authentication in main.wasp​

    Let's start with adding the following to our main.wasp file:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the user entity (we'll define it next)
        userEntity: User,
        methods: {
          // 2. Enable email authentication
          email: {
            // 3. Specify the email from field
            fromField: {
              name: "My App Postman",
              email: "hello@itsme.com"
            },
            // 4. Specify the email verification and password reset options (we'll talk about them later)
            emailVerification: {
              clientRoute: EmailVerificationRoute,
            },
            passwordReset: {
              clientRoute: PasswordResetRoute,
            },
          },
        },
        onAuthFailedRedirectTo: "/login",
        onAuthSucceededRedirectTo: "/"
      },
    }

    Read more about the email auth method options here.

    2. Add the User Entity​

    The User entity can be as simple as including only the id field:

    main.wasp
    // 5. Define the user entity
    entity User {=psl
        id                        Int           @id @default(autoincrement())
        // Add your own fields below
        // ...
    psl=}

    You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

    3. Add the Routes and Pages​

    Next, we need to define the routes and pages for the authentication pages.

    Add the following to the main.wasp file:

    main.wasp
    // ...

    // 6. Define the routes
    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { Login } from "@src/pages/auth.jsx"
    }

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { Signup } from "@src/pages/auth.jsx"
    }

    route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
    page RequestPasswordResetPage {
      component: import { RequestPasswordReset } from "@src/pages/auth.jsx",
    }

    route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
    page PasswordResetPage {
      component: import { PasswordReset } from "@src/pages/auth.jsx",
    }

    route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
    page EmailVerificationPage {
      component: import { EmailVerification } from "@src/pages/auth.jsx",
    }

    We'll define the React components for these pages in the src/pages/auth.tsx file below.

    4. Create the Client Pages​

    info

    We are using Tailwind CSS to style the pages. Read more about how to add it here.

    Let's create a auth.tsx file in the src/pages folder and add the following to it:

    src/pages/auth.jsx
    import {
      LoginForm,
      SignupForm,
      VerifyEmailForm,
      ForgotPasswordForm,
      ResetPasswordForm,
    } from 'wasp/client/auth'
    import { Link } from 'react-router-dom'

    export function Login() {
      return (
        <Layout>
          <LoginForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            Don't have an account yet? <Link to="/signup">go to signup</Link>.
          </span>
          <br />
          <span className="text-sm font-medium text-gray-900">
            Forgot your password? <Link to="/request-password-reset">reset it</Link>
            .
          </span>
        </Layout>
      );
    }

    export function Signup() {
      return (
        <Layout>
          <SignupForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            I already have an account (<Link to="/login">go to login</Link>).
          </span>
        </Layout>
      );
    }

    export function EmailVerification() {
      return (
        <Layout>
          <VerifyEmailForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            If everything is okay, <Link to="/login">go to login</Link>
          </span>
        </Layout>
      );
    }

    export function RequestPasswordReset() {
      return (
        <Layout>
          <ForgotPasswordForm />
        </Layout>
      );
    }

    export function PasswordReset() {
      return (
        <Layout>
          <ResetPasswordForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            If everything is okay, <Link to="/login">go to login</Link>
          </span>
        </Layout>
      );
    }

    // A layout component to center the content
    export function Layout({ children }) {
      return (
        <div className="w-full h-full bg-white">
          <div className="min-w-full min-h-[75vh] flex items-center justify-center">
            <div className="w-full h-full max-w-sm p-5 bg-white">
              <div>{children}</div>
            </div>
          </div>
        </div>
      );
    }

    We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

    5. Set up an Email Sender​

    To support e-mail verification and password reset flows, we need an e-mail sender. Luckily, Wasp supports several email providers out of the box.

    We'll use the Dummy provider to speed up the setup. It just logs the emails to the console instead of sending them. You can use any of the supported email providers.

    To set up the Dummy provider to send emails, add the following to the main.wasp file:

    main.wasp
    app myApp {
      // ...
      // 7. Set up the email sender
      emailSender: {
        provider: Dummy,
      }
    }

    Conclusion​

    That's it! We have set up email authentication in our app. 🎉

    Running wasp db migrate-dev and then wasp start should give you a working app with email authentication. If you want to put some of the pages behind authentication, read the auth overview.

    Login and Signup Flows​

    Login​

    Auth UI

    Signup​

    Auth UI

    Some of the behavior you get out of the box:

    1. Rate limiting

      We are limiting the rate of sign-up requests to 1 request per minute per email address. This is done to prevent spamming.

    2. Preventing user email leaks

      If somebody tries to signup with an email that already exists and it's verified, we pretend that the account was created instead of saying it's an existing account. This is done to prevent leaking the user's email address.

    3. Allowing registration for unverified emails

      If a user tries to register with an existing but unverified email, we'll allow them to do that. This is done to prevent bad actors from locking out other users from registering with their email address.

    4. Password validation

      Read more about the default password validation rules and how to override them in auth overview docs.

    Email Verification Flow​

    Automatic email verification in development

    In development mode, you can skip the email verification step by setting the SKIP_EMAIL_VERIFICATION_IN_DEV environment variable to true in your .env.server file:

    .env.server
    SKIP_EMAIL_VERIFICATION_IN_DEV=true

    This is useful when you are developing your app and don't want to go through the email verification flow every time you sign up. It can be also useful when you are writing automated tests for your app.

    By default, Wasp requires the e-mail to be verified before allowing the user to log in. This is done by sending a verification email to the user's email address and requiring the user to click on a link in the email to verify their email address.

    Our setup looks like this:

    main.wasp
    // ...

    emailVerification: {
        clientRoute: EmailVerificationRoute,
    }

    When the user receives an e-mail, they receive a link that goes to the client route specified in the clientRoute field. In our case, this is the EmailVerificationRoute route we defined in the main.wasp file.

    The content of the e-mail can be customized, read more about it here.

    Email Verification Page​

    We defined our email verification page in the auth.tsx file.

    Auth UI

    Password Reset Flow​

    Users can request a password and then they'll receive an e-mail with a link to reset their password.

    Some of the behavior you get out of the box:

    1. Rate limiting

      We are limiting the rate of sign-up requests to 1 request per minute per email address. This is done to prevent spamming.

    2. Preventing user email leaks

      If somebody requests a password reset with an unknown email address, we'll give back the same response as if the user requested a password reset successfully. This is done to prevent leaking information.

    Our setup in main.wasp looks like this:

    main.wasp
    // ...

    passwordReset: {
        clientRoute: PasswordResetRoute,
    }

    Request Password Reset Page​

    Users request their password to be reset by going to the /request-password-reset route. We defined our request password reset page in the auth.tsx file.

    Request password reset page

    Password Reset Page​

    When the user receives an e-mail, they receive a link that goes to the client route specified in the clientRoute field. In our case, this is the PasswordResetRoute route we defined in the main.wasp file.

    Request password reset page

    Users can enter their new password there.

    The content of the e-mail can be customized, read more about it here.

    Creating a Custom Sign-up Action​

    Creating a custom sign-up action

    We don't recommend creating a custom sign-up action unless you have a good reason to do so. It is a complex process and you can easily make a mistake that will compromise the security of your app.

    The code of your custom sign-up action can look like this:

    main.wasp
    // ...

    action customSignup {
      fn: import { signup } from "@src/auth/signup.js",
    }
    src/auth/signup.js
    import {
      ensurePasswordIsPresent,
      ensureValidPassword,
      ensureValidEmail,
      createProviderId,
      sanitizeAndSerializeProviderData,
      deserializeAndSanitizeProviderData,
      findAuthIdentity,
      createUser,
      createEmailVerificationLink,
      sendEmailVerificationEmail,
    } from 'wasp/server/auth'

    export const signup = async (args, _context) => {
      ensureValidEmail(args)
      ensurePasswordIsPresent(args)
      ensureValidPassword(args)

      try {
        const providerId = createProviderId('email', args.email)
        const existingAuthIdentity = await findAuthIdentity(providerId)

        if (existingAuthIdentity) {
          const providerData = deserializeAndSanitizeProviderData(existingAuthIdentity.providerData)
          // Your custom code here
        } else {
          // sanitizeAndSerializeProviderData will hash the user's password
          const newUserProviderData = await sanitizeAndSerializeProviderData({
              hashedPassword: args.password,
              isEmailVerified: false,
              emailVerificationSentAt: null,
              passwordResetSentAt: null,
          })
          await createUser(
            providerId,
            providerData,
            // Any additional data you want to store on the User entity
            {},
          )

          // Verification link links to a client route e.g. /email-verification
          const verificationLink = await createEmailVerificationLink(args.email, '/email-verification');
          try {
              await sendEmailVerificationEmail(
                  args.email,
                  {
                      from: {
                        name: "My App Postman",
                        email: "hello@itsme.com",
                      },
                      to: args.email,
                      subject: "Verify your email",
                      text: `Click the link below to verify your email: ${verificationLink}`,
                      html: `
                          <p>Click the link below to verify your email</p>
                          <a href="${verificationLink}">Verify email</a>
                      `,
                  }
              );
          } catch (e: unknown) {
              console.error("Failed to send email verification email:", e);
              throw new HttpError(500, "Failed to send email verification email.");
          } 
        }
      } catch (e) {
        return {
          success: false,
          message: e.message,
        }
      }

      // Your custom code after sign-up.
      // ...

      return {
        success: true,
        message: 'User created successfully',
      }
    }

    We suggest using the built-in field validators for your authentication flow. You can import them from wasp/server/auth. These are the same validators that Wasp uses internally for the default authentication flow.

    Email​

    • ensureValidEmail(args)

      Checks if the email is valid and throws an error if it's not. Read more about the validation rules here.

    Password​

    • ensurePasswordIsPresent(args)

      Checks if the password is present and throws an error if it's not.

    • ensureValidPassword(args)

      Checks if the password is valid and throws an error if it's not. Read more about the validation rules here.

    Using Auth​

    To read more about how to set up the logout button and how to get access to the logged-in user in our client and server code, read the auth overview docs.

    getEmail​

    If you are looking to access the user's email in your code, you can do that by accessing the info about the user that is stored in the user.auth.identities array.

    To make things a bit easier for you, Wasp offers the getEmail helper.

    The getEmail helper returns the user's email or null if the user doesn't have an email auth identity.

    src/MainPage.jsx
    import { getEmail } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const email = getEmail(user)
      // ...
    }
    src/tasks.js
    import { getEmail } from 'wasp/auth'

    export const createTask = async (args, context) => {
      const email = getEmail(context.user)
      // ...
    }

    API Reference​

    Let's go over the options we can specify when using email authentication.

    userEntity fields​

    main.wasp
    app myApp {
      title: "My app",
      // ...

      auth: {
        userEntity: User,
        methods: {
          email: {
            // We'll explain these options below
          },
        },
        onAuthFailedRedirectTo: "/someRoute"
      },
      // ...
    }

    entity User {=psl
        id                        Int           @id @default(autoincrement())
    psl=}

    The user entity needs to have the following fields:

    • id required

      It can be of any type, but it needs to be marked with @id

    You can add any other fields you want to the user entity. Make sure to also define them in the userSignupFields field if they need to be set during the sign-up process.

    Fields in the email dict​

    main.wasp
    app myApp {
      title: "My app",
      // ...

      auth: {
        userEntity: User,
        methods: {
          email: {
            userSignupFields: import { userSignupFields } from "@src/auth.js",
            fromField: {
              name: "My App",
              email: "hello@itsme.com"
            },
            emailVerification: {
              clientRoute: EmailVerificationRoute,
              getEmailContentFn: import { getVerificationEmailContent } from "@src/auth/email.js",
            },
            passwordReset: {
              clientRoute: PasswordResetRoute,
              getEmailContentFn: import { getPasswordResetEmailContent } from "@src/auth/email.js",
            },
          },
        },
        onAuthFailedRedirectTo: "/someRoute"
      },
      // ...
    }

    userSignupFields: ExtImport​

    userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

    src/auth.js
    import { defineUserSignupFields } from 'wasp/server/auth'

    export const userSignupFields = defineUserSignupFields({
      address: (data) => {
        if (!data.address) {
          throw new Error('Address is required')
        }
        return data.address
      }
      phone: (data) => data.phone,
    })
    Read more about the `userSignupFields` function [here](./overview#1-defining-extra-fields).

    fromField: EmailFromField required​

    fromField is a dict that specifies the name and e-mail address of the sender of the e-mails sent by your app.

    It has the following fields:

    • name: name of the sender
    • email: e-mail address of the sender required

    emailVerification: EmailVerificationConfig required​

    emailVerification is a dict that specifies the details of the e-mail verification process.

    It has the following fields:

    • clientRoute: Route: a route that is used for the user to verify their e-mail address. required

      Client route should handle the process of taking a token from the URL and sending it to the server to verify the e-mail address. You can use our verifyEmail action for that.

      src/pages/EmailVerificationPage.jsx
      import { verifyEmail } from 'wasp/client/auth'
      ...
      await verifyEmail({ token });
      note

      We used Auth UI above to avoid doing this work of sending the token to the server manually.

    • getEmailContentFn: ExtImport: a function that returns the content of the e-mail that is sent to the user.

      Defining getEmailContentFn can be done by defining a file in the src directory.

      src/email.js
      export const getVerificationEmailContent = ({ verificationLink }) => ({
        subject: 'Verify your email',
        text: `Click the link below to verify your email: ${verificationLink}`,
        html: `
              <p>Click the link below to verify your email</p>
              <a href="${verificationLink}">Verify email</a>
          `,
      })
      This is the default content of the e-mail, you can customize it to your liking.

    passwordReset: PasswordResetConfig required​

    passwordReset is a dict that specifies the password reset process.

    It has the following fields:

    • clientRoute: Route: a route that is used for the user to reset their password. required

      Client route should handle the process of taking a token from the URL and a new password from the user and sending it to the server. You can use our requestPasswordReset and resetPassword actions to do that.

      src/pages/ForgotPasswordPage.jsx
      import { requestPasswordReset } from 'wasp/client/auth'
      ...
      await requestPasswordReset({ email });
      src/pages/PasswordResetPage.jsx
      import { resetPassword } from 'wasp/client/auth'
      ...
      await resetPassword({ password, token })
      note

      We used Auth UI above to avoid doing this work of sending the password request and the new password to the server manually.

    • getEmailContentFn: ExtImport: a function that returns the content of the e-mail that is sent to the user.

      Defining getEmailContentFn is done by defining a function that looks like this:

      src/email.js
      export const getPasswordResetEmailContent = ({ passwordResetLink }) => ({
        subject: 'Password reset',
        text: `Click the link below to reset your password: ${passwordResetLink}`,
        html: `
              <p>Click the link below to reset your password</p>
              <a href="${passwordResetLink}">Reset password</a>
          `,
      })
      This is the default content of the e-mail, you can customize it to your liking.
    + + \ No newline at end of file diff --git a/docs/auth/entities.html b/docs/auth/entities.html index 5ece2eeaab..1aa5a8a0d9 100644 --- a/docs/auth/entities.html +++ b/docs/auth/entities.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Auth Entities

    Wasp supports multiple different authentication methods and for each method, we need to store different information about the user. For example, if you are using the Username & password authentication method, we need to store the user's username and password. On the other hand, if you are using the Email authentication method, you will need to store the user's email, password and for example, their email verification status.

    Entities Explained​

    To store user information, Wasp creates a few entities behind the scenes. In this section, we will explain what entities are created and how they are connected.

    User Entity​

    When you want to add authentication to your app, you need to specify the user entity e.g. User in your Wasp file. This entity is a "business logic user" which represents a user of your app.

    You can use this entity to store any information about the user that you want to store. For example, you might want to store the user's name or address. You can also use the user entity to define the relations between users and other entities in your app. For example, you might want to define a relation between a user and the tasks that they have created.

    entity User {=psl
      id Int @id @default(autoincrement())
      // Any other fields you want to store about the user
    psl=}

    You own the user entity and you can modify it as you wish. You can add new fields to it, remove fields from it, or change the type of the fields. You can also add new relations to it or remove existing relations from it.

    Auth Entities in a Wasp App
    Auth Entities in a Wasp App

    On the other hand, the Auth, AuthIdentity and Session entities are created behind the scenes and are used to store the user's login credentials. You as the developer don't need to care about this entity most of the time. Wasp owns these entities.

    In the case you want to create a custom signup action, you will need to use the Auth and AuthIdentity entities directly.

    Example App Model​

    Let's imagine we created a simple tasks management app:

    • The app has email and Google-based auth.
    • Users can create tasks and see the tasks that they have created.

    Let's look at how would that look in the database:

    Example of Auth Entities
    Example of Auth Entities

    If we take a look at an example user in the database, we can see:

    • The business logic user, User is connected to multiple Task entities.
      • In this example, "Example User" has two tasks.
    • The User is connected to exactly one Auth entity.
    • Each Auth entity can have multiple AuthIdentity entities.
      • In this example, the Auth entity has two AuthIdentity entities: one for the email-based auth and one for the Google-based auth.
    • Each Auth entity can have multiple Session entities.
      • In this example, the Auth entity has one Session entity.
    Using multiple auth identities for a single user

    Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

    Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

    Auth Entity internal​

    Wasp's internal Auth entity is used to connect the business logic user, User with the user's login credentials.

    entity Auth {=psl
      id         String         @id @default(uuid())
      userId     Int?           @unique
      // Wasp injects this relation on the User entity as well
      user       User?          @relation(fields: [userId], references: [id], onDelete: Cascade) 
      identities AuthIdentity[]
      sessions   Session[]
    psl=}

    The Auth fields:

    • id is a unique identifier of the Auth entity.
    • userId is a foreign key to the User entity.
      • It is used to connect the Auth entity with the business logic user.
    • user is a relation to the User entity.
      • This relation is injected on the User entity as well.
    • identities is a relation to the AuthIdentity entity.
    • sessions is a relation to the Session entity.

    AuthIdentity Entity internal​

    The AuthIdentity entity is used to store the user's login credentials for various authentication methods.

    entity AuthIdentity {=psl
      providerName   String
      providerUserId String
      providerData   String @default("{}")
      authId         String
      auth           Auth   @relation(fields: [authId], references: [id], onDelete: Cascade)

      @@id([providerName, providerUserId])  
    psl=}

    The AuthIdentity fields:

    • providerName is the name of the authentication provider.
      • For example, email or google.
    • providerUserId is the user's ID in the authentication provider.
      • For example, the user's email or Google ID.
    • providerData is a JSON string that contains additional data about the user from the authentication provider.
    • authId is a foreign key to the Auth entity.
      • It is used to connect the AuthIdentity entity with the Auth entity.
    • auth is a relation to the Auth entity.

    Session Entity internal​

    The Session entity is used to store the user's session information. It is used to keep the user logged in between page refreshes.

    entity Session {=psl
      id        String   @id @unique
      expiresAt DateTime
      userId    String
      auth      Auth     @relation(references: [id], fields: [userId], onDelete: Cascade)

      @@index([userId])
    psl=}

    The Session fields:

    • id is a unique identifier of the Session entity.
    • expiresAt is the date when the session expires.
    • userId is a foreign key to the Auth entity.
      • It is used to connect the Session entity with the Auth entity.
    • auth is a relation to the Auth entity.

    Accessing the Auth Fields​

    If you are looking to access the user's email or username in your code, you can do that by accessing the info about the user that is stored in the AuthIdentity entity.

    Everywhere where Wasp gives you the user object, it also includes the auth relation with the identities relation. This means that you can access the auth identity info by using the user.auth.identities array.

    To make things a bit easier for you, Wasp offers a few helper functions that you can use to access the auth identity info.

    getEmail​

    The getEmail helper returns the user's email or null if the user doesn't have an email auth identity.

    src/MainPage.jsx
    import { getEmail } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const email = getEmail(user)
      // ...
    }
    src/tasks.js
    import { getEmail } from 'wasp/auth'

    export const createTask = async (args, context) => {
      const email = getEmail(context.user)
      // ...
    }

    getUsername​

    The getUsername helper returns the user's username or null if the user doesn't have a username auth identity.

    src/MainPage.jsx
    import { getUsername } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const username = getUsername(user)
      // ...
    }
    src/tasks.js
    import { getUsername } from 'wasp/auth'

    export const createTask = async (args, context) => {
      const username = getUsername(context.user)
      // ...
    }

    getFirstProviderUserId​

    The getFirstProviderUserId helper returns the first user ID (e.g. username or email) that it finds for the user or null if it doesn't find any.

    As mentioned before, the providerUserId field is how providers identify our users. For example, the user's username in the case of the username auth or the user's email in the case of the email auth. This can be useful if you support multiple authentication methods and you need any ID that identifies the user in your app.

    src/MainPage.jsx
    import { getFirstProviderUserId } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const userId = getFirstProviderUserId(user)
      // ...
    }
    src/tasks.js
    import { getFirstProviderUserId } from 'wasp/auth'

    export const createTask = async (args, context) => {
      const userId = getFirstProviderUserId(context.user)
      // ...
    }

    findUserIdentity​

    You can find a specific auth identity by using the findUserIdentity helper function. This function takes a user and a providerName and returns the first providerName identity that it finds or null if it doesn't find any.

    Possible provider names are:

    • email
    • username
    • google
    • github

    This can be useful if you want to check if the user has a specific auth identity. For example, you might want to check if the user has an email auth identity or Google auth identity.

    src/MainPage.jsx
    import { findUserIdentity } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const emailIdentity = findUserIdentity(user, 'email')
      const googleIdentity = findUserIdentity(user, 'google')
      if (emailIdentity) {
        // ...
      } else if (googleIdentity) {
        // ...
      }
      // ...
    }
    src/tasks.js
    import { findUserIdentity } from 'wasp/client/auth'

    export const createTask = async (args, context) => {
      const emailIdentity = findUserIdentity(context.user, 'email')
      const googleIdentity = findUserIdentity(context.user, 'google')
      if (emailIdentity) {
        // ...
      } else if (googleIdentity) {
        // ...
      }
      // ...
    }

    Custom Signup Action​

    Let's take a look at how you can use the Auth and AuthIdentity entities to create custom login and signup actions. For example, you might want to create a custom signup action that creates a user in your app and also creates a user in a third-party service.

    Custom Signup Examples

    In the Email section of the docs we give you an example for custom email signup and in the Username & password section of the docs we give you an example for custom username & password signup.

    Below is a simplified version of a custom signup action which you probably wouldn't use in your app but it shows you how you can use the Auth and AuthIdentity entities to create a custom signup action.

    main.wasp
    // ...

    action customSignup {
      fn: import { signup } from "@src/auth/signup.js",
      entities: [User]
    }
    src/auth/signup.js
    import {
      createProviderId,
      sanitizeAndSerializeProviderData,
      createUser,
    } from 'wasp/server/auth'

    export const signup = async (args, { entities: { User } }) => {
      try {
        // Provider ID is a combination of the provider name and the provider user ID
        // And it is used to uniquely identify the user in your app
        const providerId = createProviderId('username', args.username)
        // sanitizeAndSerializeProviderData hashes the password and returns a JSON string
        const providerData = await sanitizeAndSerializeProviderData({
          hashedPassword: args.password,
        })

        await createUser(
          providerId,
          providerData,
          // Any additional data you want to store on the User entity
          {},
        )

        // This is equivalent to:
        // await User.create({
        //   data: {
        //     auth: {
        //       create: {
        //         identities: {
        //             create: {
        //                 providerName: 'username',
        //                 providerUserId: args.username
        //                 providerData,
        //             },
        //         },
        //       }
        //     },
        //   }
        // })
      } catch (e) {
        return {
          success: false,
          message: e.message,
        }
      }

      // Your custom code after sign-up.
      // ...

      return {
        success: true,
        message: 'User created successfully',
      }
    }

    You can use whichever method suits your needs better: either the createUser function or Prisma's User.create method. The createUser function is a bit more convenient to use because it hides some of the complexity. On the other hand, the User.create method gives you more control over the data that is stored in the Auth and AuthIdentity entities.

    - - +
    +
    Version: 0.13.0

    Auth Entities

    Wasp supports multiple different authentication methods and for each method, we need to store different information about the user. For example, if you are using the Username & password authentication method, we need to store the user's username and password. On the other hand, if you are using the Email authentication method, you will need to store the user's email, password and for example, their email verification status.

    Entities Explained​

    To store user information, Wasp creates a few entities behind the scenes. In this section, we will explain what entities are created and how they are connected.

    User Entity​

    When you want to add authentication to your app, you need to specify the user entity e.g. User in your Wasp file. This entity is a "business logic user" which represents a user of your app.

    You can use this entity to store any information about the user that you want to store. For example, you might want to store the user's name or address. You can also use the user entity to define the relations between users and other entities in your app. For example, you might want to define a relation between a user and the tasks that they have created.

    entity User {=psl
      id Int @id @default(autoincrement())
      // Any other fields you want to store about the user
    psl=}

    You own the user entity and you can modify it as you wish. You can add new fields to it, remove fields from it, or change the type of the fields. You can also add new relations to it or remove existing relations from it.

    Auth Entities in a Wasp App
    Auth Entities in a Wasp App

    On the other hand, the Auth, AuthIdentity and Session entities are created behind the scenes and are used to store the user's login credentials. You as the developer don't need to care about this entity most of the time. Wasp owns these entities.

    In the case you want to create a custom signup action, you will need to use the Auth and AuthIdentity entities directly.

    Example App Model​

    Let's imagine we created a simple tasks management app:

    • The app has email and Google-based auth.
    • Users can create tasks and see the tasks that they have created.

    Let's look at how would that look in the database:

    Example of Auth Entities
    Example of Auth Entities

    If we take a look at an example user in the database, we can see:

    • The business logic user, User is connected to multiple Task entities.
      • In this example, "Example User" has two tasks.
    • The User is connected to exactly one Auth entity.
    • Each Auth entity can have multiple AuthIdentity entities.
      • In this example, the Auth entity has two AuthIdentity entities: one for the email-based auth and one for the Google-based auth.
    • Each Auth entity can have multiple Session entities.
      • In this example, the Auth entity has one Session entity.
    Using multiple auth identities for a single user

    Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

    Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

    Auth Entity internal​

    Wasp's internal Auth entity is used to connect the business logic user, User with the user's login credentials.

    entity Auth {=psl
      id         String         @id @default(uuid())
      userId     Int?           @unique
      // Wasp injects this relation on the User entity as well
      user       User?          @relation(fields: [userId], references: [id], onDelete: Cascade) 
      identities AuthIdentity[]
      sessions   Session[]
    psl=}

    The Auth fields:

    • id is a unique identifier of the Auth entity.
    • userId is a foreign key to the User entity.
      • It is used to connect the Auth entity with the business logic user.
    • user is a relation to the User entity.
      • This relation is injected on the User entity as well.
    • identities is a relation to the AuthIdentity entity.
    • sessions is a relation to the Session entity.

    AuthIdentity Entity internal​

    The AuthIdentity entity is used to store the user's login credentials for various authentication methods.

    entity AuthIdentity {=psl
      providerName   String
      providerUserId String
      providerData   String @default("{}")
      authId         String
      auth           Auth   @relation(fields: [authId], references: [id], onDelete: Cascade)

      @@id([providerName, providerUserId])  
    psl=}

    The AuthIdentity fields:

    • providerName is the name of the authentication provider.
      • For example, email or google.
    • providerUserId is the user's ID in the authentication provider.
      • For example, the user's email or Google ID.
    • providerData is a JSON string that contains additional data about the user from the authentication provider.
    • authId is a foreign key to the Auth entity.
      • It is used to connect the AuthIdentity entity with the Auth entity.
    • auth is a relation to the Auth entity.

    Session Entity internal​

    The Session entity is used to store the user's session information. It is used to keep the user logged in between page refreshes.

    entity Session {=psl
      id        String   @id @unique
      expiresAt DateTime
      userId    String
      auth      Auth     @relation(references: [id], fields: [userId], onDelete: Cascade)

      @@index([userId])
    psl=}

    The Session fields:

    • id is a unique identifier of the Session entity.
    • expiresAt is the date when the session expires.
    • userId is a foreign key to the Auth entity.
      • It is used to connect the Session entity with the Auth entity.
    • auth is a relation to the Auth entity.

    Accessing the Auth Fields​

    If you are looking to access the user's email or username in your code, you can do that by accessing the info about the user that is stored in the AuthIdentity entity.

    Everywhere where Wasp gives you the user object, it also includes the auth relation with the identities relation. This means that you can access the auth identity info by using the user.auth.identities array.

    To make things a bit easier for you, Wasp offers a few helper functions that you can use to access the auth identity info.

    getEmail​

    The getEmail helper returns the user's email or null if the user doesn't have an email auth identity.

    src/MainPage.jsx
    import { getEmail } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const email = getEmail(user)
      // ...
    }
    src/tasks.js
    import { getEmail } from 'wasp/auth'

    export const createTask = async (args, context) => {
      const email = getEmail(context.user)
      // ...
    }

    getUsername​

    The getUsername helper returns the user's username or null if the user doesn't have a username auth identity.

    src/MainPage.jsx
    import { getUsername } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const username = getUsername(user)
      // ...
    }
    src/tasks.js
    import { getUsername } from 'wasp/auth'

    export const createTask = async (args, context) => {
      const username = getUsername(context.user)
      // ...
    }

    getFirstProviderUserId​

    The getFirstProviderUserId helper returns the first user ID (e.g. username or email) that it finds for the user or null if it doesn't find any.

    As mentioned before, the providerUserId field is how providers identify our users. For example, the user's username in the case of the username auth or the user's email in the case of the email auth. This can be useful if you support multiple authentication methods and you need any ID that identifies the user in your app.

    src/MainPage.jsx
    import { getFirstProviderUserId } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const userId = getFirstProviderUserId(user)
      // ...
    }
    src/tasks.js
    import { getFirstProviderUserId } from 'wasp/auth'

    export const createTask = async (args, context) => {
      const userId = getFirstProviderUserId(context.user)
      // ...
    }

    findUserIdentity​

    You can find a specific auth identity by using the findUserIdentity helper function. This function takes a user and a providerName and returns the first providerName identity that it finds or null if it doesn't find any.

    Possible provider names are:

    • email
    • username
    • google
    • github

    This can be useful if you want to check if the user has a specific auth identity. For example, you might want to check if the user has an email auth identity or Google auth identity.

    src/MainPage.jsx
    import { findUserIdentity } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const emailIdentity = findUserIdentity(user, 'email')
      const googleIdentity = findUserIdentity(user, 'google')
      if (emailIdentity) {
        // ...
      } else if (googleIdentity) {
        // ...
      }
      // ...
    }
    src/tasks.js
    import { findUserIdentity } from 'wasp/client/auth'

    export const createTask = async (args, context) => {
      const emailIdentity = findUserIdentity(context.user, 'email')
      const googleIdentity = findUserIdentity(context.user, 'google')
      if (emailIdentity) {
        // ...
      } else if (googleIdentity) {
        // ...
      }
      // ...
    }

    Custom Signup Action​

    Let's take a look at how you can use the Auth and AuthIdentity entities to create custom login and signup actions. For example, you might want to create a custom signup action that creates a user in your app and also creates a user in a third-party service.

    Custom Signup Examples

    In the Email section of the docs we give you an example for custom email signup and in the Username & password section of the docs we give you an example for custom username & password signup.

    Below is a simplified version of a custom signup action which you probably wouldn't use in your app but it shows you how you can use the Auth and AuthIdentity entities to create a custom signup action.

    main.wasp
    // ...

    action customSignup {
      fn: import { signup } from "@src/auth/signup.js",
      entities: [User]
    }
    src/auth/signup.js
    import {
      createProviderId,
      sanitizeAndSerializeProviderData,
      createUser,
    } from 'wasp/server/auth'

    export const signup = async (args, { entities: { User } }) => {
      try {
        // Provider ID is a combination of the provider name and the provider user ID
        // And it is used to uniquely identify the user in your app
        const providerId = createProviderId('username', args.username)
        // sanitizeAndSerializeProviderData hashes the password and returns a JSON string
        const providerData = await sanitizeAndSerializeProviderData({
          hashedPassword: args.password,
        })

        await createUser(
          providerId,
          providerData,
          // Any additional data you want to store on the User entity
          {},
        )

        // This is equivalent to:
        // await User.create({
        //   data: {
        //     auth: {
        //       create: {
        //         identities: {
        //             create: {
        //                 providerName: 'username',
        //                 providerUserId: args.username
        //                 providerData,
        //             },
        //         },
        //       }
        //     },
        //   }
        // })
      } catch (e) {
        return {
          success: false,
          message: e.message,
        }
      }

      // Your custom code after sign-up.
      // ...

      return {
        success: true,
        message: 'User created successfully',
      }
    }

    You can use whichever method suits your needs better: either the createUser function or Prisma's User.create method. The createUser function is a bit more convenient to use because it hides some of the complexity. On the other hand, the User.create method gives you more control over the data that is stored in the Auth and AuthIdentity entities.

    + + \ No newline at end of file diff --git a/docs/auth/overview.html b/docs/auth/overview.html index 894eb1e65c..181397b273 100644 --- a/docs/auth/overview.html +++ b/docs/auth/overview.html @@ -19,15 +19,15 @@ - - + + -
    -
    Version: 0.13.0

    Overview

    Auth is an essential piece of any serious application. That's why Wasp provides authentication and authorization support out of the box.

    Here's a 1-minute tour of how full-stack auth works in Wasp:

    Enabling auth for your app is optional and can be done by configuring the auth field of your app declaration:

    main.wasp
    app MyApp {
      title: "My app",
      //...
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {}, // use this or email, not both
          email: {}, // use this or usernameAndPassword, not both
          google: {},
          gitHub: {},
        },
        onAuthFailedRedirectTo: "/someRoute"
      }
    }

    //...

    Read more about the auth field options in the API Reference section.

    We will provide a quick overview of auth in Wasp and link to more detailed documentation for each auth method.

    Available auth methods​

    Wasp supports the following auth methods:

    Email »

    Email verification, password reset, etc.

    Username & Password »

    The simplest way to get started

    Google »

    Users sign in with their Google account

    Github »

    Users sign in with their Github account

    Keycloak »

    Users sign in with their Keycloak account

    Click on each auth method for more details.

    Let's say we enabled the Username & password authentication.

    We get an auth backend with signup and login endpoints. We also get the user object in our Operations and we can decide what to do based on whether the user is logged in or not.

    We would also get the Auth UI generated for us. We can set up our login and signup pages where our users can create their account and login. We can then protect certain pages by setting authRequired: true for them. This will make sure that only logged-in users can access them.

    We will also have access to the user object in our frontend code, so we can show different UI to logged-in and logged-out users. For example, we can show the user's name in the header alongside a logout button or a login button if the user is not logged in.

    Protecting a page with authRequired​

    When declaring a page, you can set the authRequired property.

    If you set it to true, only authenticated users can access the page. Unauthenticated users are redirected to a route defined by the app.auth.onAuthFailedRedirectTo field.

    main.wasp
    page MainPage {
      component: import Main from "@src/pages/Main",
      authRequired: true
    }
    Requires auth method

    You can only use authRequired if your app uses one of the available auth methods.

    If authRequired is set to true, the page's React component (specified by the component property) receives the user object as a prop. Read more about the user object in the Accessing the logged-in user section.

    Logout action​

    We provide an action for logging out the user. Here's how you can use it:

    src/components/LogoutButton.jsx
    import { logout } from 'wasp/client/auth'

    const LogoutButton = () => {
      return <button onClick={logout}>Logout</button>
    }

    Accessing the logged-in user​

    You can get access to the user object both on the server and on the client. The user object contains the logged-in user's data.

    The user object has all the fields that you defined in your User entity, plus the auth field which contains the auth identities connected to the user. For example, if the user signed up with their email, the user object might look something like this:

    const user = {
      id: "19c7d164-b5cb-4dde-a0cc-0daea77cf854",

      // Your entity's fields.
      address: "My address",
      // ...

      // Auth identities connected to the user.
      auth: {
        id: "26ab6f96-ed76-4ee5-9ac3-2fd0bf19711f",
        identities: [
          {
            providerName: "email",
            providerUserId: "some@email.com",
            providerData: { ... },
          },
        ]
      },
    }

    You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

    On the client​

    There are two ways to access the user object on the client:

    • the user prop
    • the useAuth hook

    Using the user prop​

    If the page's declaration sets authRequired to true, the page's React component receives the user object as a prop:

    main.wasp
    // ...

    page AccountPage {
      component: import Account from "@src/pages/Account",
      authRequired: true
    }
    src/pages/Account.jsx
    import Button from './Button'
    import { logout } from 'wasp/client/auth'

    const AccountPage = ({ user }) => {
      return (
        <div>
          <Button onClick={logout}>Logout</Button>
          {JSON.stringify(user, null, 2)}
        </div>
      )
    }

    export default AccountPage

    Using the useAuth hook​

    Wasp provides a React hook you can use in the client components - useAuth.

    This hook is a thin wrapper over Wasp's useQuery hook and returns data in the same format.

    src/pages/MainPage.jsx
    import { useAuth, logout } from 'wasp/client/auth'
    import { Link } from 'react-router-dom'
    import Todo from '../Todo'

    export function Main() {
      const { data: user } = useAuth()

      if (!user) {
        return (
          <span>
            Please <Link to="/login">login</Link> or{' '}
            <Link to="/signup">sign up</Link>.
          </span>
        )
      } else {
        return (
          <>
            <button onClick={logout}>Logout</button>
            <Todo />
          </>
        )
      }
    }
    tip

    Since the user prop is only available in a page's React component: use the user prop in the page's React component and the useAuth hook in any other React component.

    On the server​

    Using the context.user object​

    When authentication is enabled, all queries and actions have access to the user object through the context argument. context.user contains all User entity's fields and the auth identities connected to the user. We strip out the hashedPassword field from the identities for security reasons.

    src/actions.js
    import { HttpError } from 'wasp/server'

    export const createTask = async (task, context) => {
      if (!context.user) {
        throw new HttpError(403)
      }

      const Task = context.entities.Task
      return Task.create({
        data: {
          description: task.description,
          user: {
            connect: { id: context.user.id },
          },
        },
      })
    }

    To implement access control in your app, each operation must check context.user and decide what to do. For example, if context.user is undefined inside a private operation, the user's access should be denied.

    When using WebSockets, the user object is also available on the socket.data object. Read more in the WebSockets section.

    Sessions​

    Wasp's auth uses sessions to keep track of the logged-in user. The session is stored in localStorage on the client and in the database on the server. Under the hood, Wasp uses the excellent Lucia Auth v3 library for session management.

    When users log in, Wasp creates a session for them and stores it in the database. The session is then sent to the client and stored in localStorage. When users log out, Wasp deletes the session from the database and from localStorage.

    User Entity​

    Password Hashing​

    If you are saving a user's password in the database, you should never save it as plain text. You can use Wasp's helper functions for serializing and deserializing provider data which will automatically hash the password for you:

    main.wasp
    // ...

    action updatePassword {
      fn: import { updatePassword } from "@src/auth",
    }
    src/auth.js
    import {
      createProviderId,
      findAuthIdentity,
      updateAuthIdentityProviderData,
      deserializeAndSanitizeProviderData,
    } from 'wasp/server/auth';

    export const updatePassword = async (args, context) => {
      const providerId = createProviderId('email', args.email)
      const authIdentity = await findAuthIdentity(providerId)
      if (!authIdentity) {
          throw new HttpError(400, "Unknown user")
      }
      
      const providerData = deserializeAndSanitizeProviderData(authIdentity.providerData)

      // Updates the password and hashes it automatically.
      await updateAuthIdentityProviderData(providerId, providerData, {
          hashedPassword: args.password,
      })
    }

    Default Validations​

    When you are using the default authentication flow, Wasp validates the fields with some default validations. These validations run if you use Wasp's built-in Auth UI or if you use the provided auth actions.

    If you decide to create your custom auth actions, you'll need to run the validations yourself.

    Default validations depend on the auth method you use.

    Username & Password​

    If you use Username & password authentication, the default validations are:

    • The username must not be empty
    • The password must not be empty, have at least 8 characters, and contain a number

    Note that usernames are stored in a case-insensitive manner.

    Email​

    If you use Email authentication, the default validations are:

    • The email must not be empty and a valid email address
    • The password must not be empty, have at least 8 characters, and contain a number

    Note that emails are stored in a case-insensitive manner.

    Customizing the Signup Process​

    Sometimes you want to include extra fields in your signup process, like first name and last name and save them in the User entity.

    For this to happen:

    • you need to define the fields that you want saved in the database,
    • you need to customize the SignupForm (in the case of Email or Username & Password auth)

    Other times, you might need to just add some extra UI elements to the form, like a checkbox for terms of service. In this case, customizing only the UI components is enough.

    Let's see how to do both.

    1. Defining Extra Fields​

    If we want to save some extra fields in our signup process, we need to tell our app they exist.

    We do that by defining an object where the keys represent the field name, and the values are functions that receive the data sent from the client* and return the value of the field.

    * We exclude the password field from this object to prevent it from being saved as plain-text in the database. The password field is handled by Wasp's auth backend.

    First, we add the auth.methods.{authMethod}.userSignupFields field in our main.wasp file. The {authMethod} depends on the auth method you are using.

    For example, if you are using Username & Password, you would add the auth.methods.usernameAndPassword.userSignupFields field:

    main.wasp
    app crudTesting {
      // ...
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {
            userSignupFields: import { userSignupFields } from "@src/auth/signup",
          },
        },
        onAuthFailedRedirectTo: "/login",
      },
    }

    entity User {=psl
      id Int @id @default(autoincrement())
      address String?
    psl=}

    Then we'll define the userSignupFields object in the src/auth/signup.js file:

    src/auth/signup.js
    import { defineUserSignupFields } from 'wasp/server/auth'

    export const userSignupFields = defineUserSignupFields({
      address: async (data) => {
        const address = data.address
        if (typeof address !== 'string') {
          throw new Error('Address is required')
        }
        if (address.length < 5) {
          throw new Error('Address must be at least 5 characters long')
        }
        return address
      },
    })

    Read more about the userSignupFields object in the API Reference.

    Keep in mind, that these field names need to exist on the userEntity you defined in your main.wasp file e.g. address needs to be a field on the User entity.

    The field function will receive the data sent from the client and it needs to return the value that will be saved into the database. If the field is invalid, the function should throw an error.

    Using Validation Libraries

    You can use any validation library you want to validate the fields. For example, you can use zod like this:

    Click to see the code
    src/auth/signup.js
    import { defineUserSignupFields } from 'wasp/server/auth'
    import * as z from 'zod'

    export const userSignupFields = defineUserSignupFields({
      address: (data) => {
        const AddressSchema = z
          .string({
            required_error: 'Address is required',
            invalid_type_error: 'Address must be a string',
          })
          .min(10, 'Address must be at least 10 characters long')
        const result = AddressSchema.safeParse(data.address)
        if (result.success === false) {
          throw new Error(result.error.issues[0].message)
        }
        return result.data
      },
    })

    Now that we defined the fields, Wasp knows how to:

    1. Validate the data sent from the client
    2. Save the data to the database

    Next, let's see how to customize Auth UI to include those fields.

    2. Customizing the Signup Component​

    Using Custom Signup Component

    If you are not using Wasp's Auth UI, you can skip this section. Just make sure to include the extra fields in your custom signup form.

    Read more about using the signup actions for:

    • email auth here
    • username & password auth here

    If you are using Wasp's Auth UI, you can customize the SignupForm component by passing the additionalFields prop to it. It can be either a list of extra fields or a render function.

    Using a List of Extra Fields​

    When you pass in a list of extra fields to the SignupForm, they are added to the form one by one, in the order you pass them in.

    Inside the list, there can be either objects or render functions (you can combine them):

    1. Objects are a simple way to describe new fields you need, but a bit less flexible than render functions.
    2. Render functions can be used to render any UI you want, but they require a bit more code. The render functions receive the react-hook-form object and the form state object as arguments.
    src/SignupPage.jsx
    import {
      SignupForm,
      FormError,
      FormInput,
      FormItemGroup,
      FormLabel,
    } from 'wasp/client/auth'

    export const SignupPage = () => {
      return (
        <SignupForm
          additionalFields={[
            /* The address field is defined using an object */
            {
              name: 'address',
              label: 'Address',
              type: 'input',
              validations: {
                required: 'Address is required',
              },
            },
            /* The phone number is defined using a render function */
            (form, state) => {
              return (
                <FormItemGroup>
                  <FormLabel>Phone Number</FormLabel>
                  <FormInput
                    {...form.register('phoneNumber', {
                      required: 'Phone number is required',
                    })}
                    disabled={state.isLoading}
                  />
                  {form.formState.errors.phoneNumber && (
                    <FormError>
                      {form.formState.errors.phoneNumber.message}
                    </FormError>
                  )}
                </FormItemGroup>
              )
            },
          ]}
        />
      )
    }

    Read more about the extra fields in the API Reference.

    Using a Single Render Function​

    Instead of passing in a list of extra fields, you can pass in a render function which will receive the react-hook-form object and the form state object as arguments. What ever the render function returns, will be rendered below the default fields.

    src/SignupPage.jsx
    import { SignupForm, FormItemGroup } from 'wasp/client/auth'

    export const SignupPage = () => {
      return (
        <SignupForm
          additionalFields={(form, state) => {
            const username = form.watch('username')
            return (
              username && (
                <FormItemGroup>
                  Hello there <strong>{username}</strong> 👋
                </FormItemGroup>
              )
            )
          }}
        />
      )
    }

    Read more about the render function in the API Reference.

    API Reference​

    Auth Fields​

    main.wasp
      title: "My app",
      //...
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {}, // use this or email, not both
          email: {}, // use this or usernameAndPassword, not both
          google: {},
          gitHub: {},
        },
        onAuthFailedRedirectTo: "/someRoute",
        signup: { ... }
      }
    }

    //...

    app.auth is a dictionary with the following fields:

    userEntity: entity required​

    The entity representing the user connected to your business logic.

    You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

    methods: dict required​

    A dictionary of auth methods enabled for the app.

    Email »

    Email verification, password reset, etc.

    Username & Password »

    The simplest way to get started

    Google »

    Users sign in with their Google account

    Github »

    Users sign in with their Github account

    Keycloak »

    Users sign in with their Keycloak account

    Click on each auth method for more details.

    onAuthFailedRedirectTo: String required​

    The route to which Wasp should redirect unauthenticated user when they try to access a private page (i.e., a page that has authRequired: true). +

    +
    Version: 0.13.0

    Overview

    Auth is an essential piece of any serious application. That's why Wasp provides authentication and authorization support out of the box.

    Here's a 1-minute tour of how full-stack auth works in Wasp:

    Enabling auth for your app is optional and can be done by configuring the auth field of your app declaration:

    main.wasp
    app MyApp {
      title: "My app",
      //...
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {}, // use this or email, not both
          email: {}, // use this or usernameAndPassword, not both
          google: {},
          gitHub: {},
        },
        onAuthFailedRedirectTo: "/someRoute"
      }
    }

    //...

    Read more about the auth field options in the API Reference section.

    We will provide a quick overview of auth in Wasp and link to more detailed documentation for each auth method.

    Available auth methods​

    Wasp supports the following auth methods:

    Email »

    Email verification, password reset, etc.

    Username & Password »

    The simplest way to get started

    Google »

    Users sign in with their Google account

    Github »

    Users sign in with their Github account

    Keycloak »

    Users sign in with their Keycloak account

    Click on each auth method for more details.

    Let's say we enabled the Username & password authentication.

    We get an auth backend with signup and login endpoints. We also get the user object in our Operations and we can decide what to do based on whether the user is logged in or not.

    We would also get the Auth UI generated for us. We can set up our login and signup pages where our users can create their account and login. We can then protect certain pages by setting authRequired: true for them. This will make sure that only logged-in users can access them.

    We will also have access to the user object in our frontend code, so we can show different UI to logged-in and logged-out users. For example, we can show the user's name in the header alongside a logout button or a login button if the user is not logged in.

    Protecting a page with authRequired​

    When declaring a page, you can set the authRequired property.

    If you set it to true, only authenticated users can access the page. Unauthenticated users are redirected to a route defined by the app.auth.onAuthFailedRedirectTo field.

    main.wasp
    page MainPage {
      component: import Main from "@src/pages/Main",
      authRequired: true
    }
    Requires auth method

    You can only use authRequired if your app uses one of the available auth methods.

    If authRequired is set to true, the page's React component (specified by the component property) receives the user object as a prop. Read more about the user object in the Accessing the logged-in user section.

    Logout action​

    We provide an action for logging out the user. Here's how you can use it:

    src/components/LogoutButton.jsx
    import { logout } from 'wasp/client/auth'

    const LogoutButton = () => {
      return <button onClick={logout}>Logout</button>
    }

    Accessing the logged-in user​

    You can get access to the user object both on the server and on the client. The user object contains the logged-in user's data.

    The user object has all the fields that you defined in your User entity, plus the auth field which contains the auth identities connected to the user. For example, if the user signed up with their email, the user object might look something like this:

    const user = {
      id: "19c7d164-b5cb-4dde-a0cc-0daea77cf854",

      // Your entity's fields.
      address: "My address",
      // ...

      // Auth identities connected to the user.
      auth: {
        id: "26ab6f96-ed76-4ee5-9ac3-2fd0bf19711f",
        identities: [
          {
            providerName: "email",
            providerUserId: "some@email.com",
            providerData: { ... },
          },
        ]
      },
    }

    You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

    On the client​

    There are two ways to access the user object on the client:

    • the user prop
    • the useAuth hook

    Using the user prop​

    If the page's declaration sets authRequired to true, the page's React component receives the user object as a prop:

    main.wasp
    // ...

    page AccountPage {
      component: import Account from "@src/pages/Account",
      authRequired: true
    }
    src/pages/Account.jsx
    import Button from './Button'
    import { logout } from 'wasp/client/auth'

    const AccountPage = ({ user }) => {
      return (
        <div>
          <Button onClick={logout}>Logout</Button>
          {JSON.stringify(user, null, 2)}
        </div>
      )
    }

    export default AccountPage

    Using the useAuth hook​

    Wasp provides a React hook you can use in the client components - useAuth.

    This hook is a thin wrapper over Wasp's useQuery hook and returns data in the same format.

    src/pages/MainPage.jsx
    import { useAuth, logout } from 'wasp/client/auth'
    import { Link } from 'react-router-dom'
    import Todo from '../Todo'

    export function Main() {
      const { data: user } = useAuth()

      if (!user) {
        return (
          <span>
            Please <Link to="/login">login</Link> or{' '}
            <Link to="/signup">sign up</Link>.
          </span>
        )
      } else {
        return (
          <>
            <button onClick={logout}>Logout</button>
            <Todo />
          </>
        )
      }
    }
    tip

    Since the user prop is only available in a page's React component: use the user prop in the page's React component and the useAuth hook in any other React component.

    On the server​

    Using the context.user object​

    When authentication is enabled, all queries and actions have access to the user object through the context argument. context.user contains all User entity's fields and the auth identities connected to the user. We strip out the hashedPassword field from the identities for security reasons.

    src/actions.js
    import { HttpError } from 'wasp/server'

    export const createTask = async (task, context) => {
      if (!context.user) {
        throw new HttpError(403)
      }

      const Task = context.entities.Task
      return Task.create({
        data: {
          description: task.description,
          user: {
            connect: { id: context.user.id },
          },
        },
      })
    }

    To implement access control in your app, each operation must check context.user and decide what to do. For example, if context.user is undefined inside a private operation, the user's access should be denied.

    When using WebSockets, the user object is also available on the socket.data object. Read more in the WebSockets section.

    Sessions​

    Wasp's auth uses sessions to keep track of the logged-in user. The session is stored in localStorage on the client and in the database on the server. Under the hood, Wasp uses the excellent Lucia Auth v3 library for session management.

    When users log in, Wasp creates a session for them and stores it in the database. The session is then sent to the client and stored in localStorage. When users log out, Wasp deletes the session from the database and from localStorage.

    User Entity​

    Password Hashing​

    If you are saving a user's password in the database, you should never save it as plain text. You can use Wasp's helper functions for serializing and deserializing provider data which will automatically hash the password for you:

    main.wasp
    // ...

    action updatePassword {
      fn: import { updatePassword } from "@src/auth",
    }
    src/auth.js
    import {
      createProviderId,
      findAuthIdentity,
      updateAuthIdentityProviderData,
      deserializeAndSanitizeProviderData,
    } from 'wasp/server/auth';

    export const updatePassword = async (args, context) => {
      const providerId = createProviderId('email', args.email)
      const authIdentity = await findAuthIdentity(providerId)
      if (!authIdentity) {
          throw new HttpError(400, "Unknown user")
      }
      
      const providerData = deserializeAndSanitizeProviderData(authIdentity.providerData)

      // Updates the password and hashes it automatically.
      await updateAuthIdentityProviderData(providerId, providerData, {
          hashedPassword: args.password,
      })
    }

    Default Validations​

    When you are using the default authentication flow, Wasp validates the fields with some default validations. These validations run if you use Wasp's built-in Auth UI or if you use the provided auth actions.

    If you decide to create your custom auth actions, you'll need to run the validations yourself.

    Default validations depend on the auth method you use.

    Username & Password​

    If you use Username & password authentication, the default validations are:

    • The username must not be empty
    • The password must not be empty, have at least 8 characters, and contain a number

    Note that usernames are stored in a case-insensitive manner.

    Email​

    If you use Email authentication, the default validations are:

    • The email must not be empty and a valid email address
    • The password must not be empty, have at least 8 characters, and contain a number

    Note that emails are stored in a case-insensitive manner.

    Customizing the Signup Process​

    Sometimes you want to include extra fields in your signup process, like first name and last name and save them in the User entity.

    For this to happen:

    • you need to define the fields that you want saved in the database,
    • you need to customize the SignupForm (in the case of Email or Username & Password auth)

    Other times, you might need to just add some extra UI elements to the form, like a checkbox for terms of service. In this case, customizing only the UI components is enough.

    Let's see how to do both.

    1. Defining Extra Fields​

    If we want to save some extra fields in our signup process, we need to tell our app they exist.

    We do that by defining an object where the keys represent the field name, and the values are functions that receive the data sent from the client* and return the value of the field.

    * We exclude the password field from this object to prevent it from being saved as plain-text in the database. The password field is handled by Wasp's auth backend.

    First, we add the auth.methods.{authMethod}.userSignupFields field in our main.wasp file. The {authMethod} depends on the auth method you are using.

    For example, if you are using Username & Password, you would add the auth.methods.usernameAndPassword.userSignupFields field:

    main.wasp
    app crudTesting {
      // ...
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {
            userSignupFields: import { userSignupFields } from "@src/auth/signup",
          },
        },
        onAuthFailedRedirectTo: "/login",
      },
    }

    entity User {=psl
      id Int @id @default(autoincrement())
      address String?
    psl=}

    Then we'll define the userSignupFields object in the src/auth/signup.js file:

    src/auth/signup.js
    import { defineUserSignupFields } from 'wasp/server/auth'

    export const userSignupFields = defineUserSignupFields({
      address: async (data) => {
        const address = data.address
        if (typeof address !== 'string') {
          throw new Error('Address is required')
        }
        if (address.length < 5) {
          throw new Error('Address must be at least 5 characters long')
        }
        return address
      },
    })

    Read more about the userSignupFields object in the API Reference.

    Keep in mind, that these field names need to exist on the userEntity you defined in your main.wasp file e.g. address needs to be a field on the User entity.

    The field function will receive the data sent from the client and it needs to return the value that will be saved into the database. If the field is invalid, the function should throw an error.

    Using Validation Libraries

    You can use any validation library you want to validate the fields. For example, you can use zod like this:

    Click to see the code
    src/auth/signup.js
    import { defineUserSignupFields } from 'wasp/server/auth'
    import * as z from 'zod'

    export const userSignupFields = defineUserSignupFields({
      address: (data) => {
        const AddressSchema = z
          .string({
            required_error: 'Address is required',
            invalid_type_error: 'Address must be a string',
          })
          .min(10, 'Address must be at least 10 characters long')
        const result = AddressSchema.safeParse(data.address)
        if (result.success === false) {
          throw new Error(result.error.issues[0].message)
        }
        return result.data
      },
    })

    Now that we defined the fields, Wasp knows how to:

    1. Validate the data sent from the client
    2. Save the data to the database

    Next, let's see how to customize Auth UI to include those fields.

    2. Customizing the Signup Component​

    Using Custom Signup Component

    If you are not using Wasp's Auth UI, you can skip this section. Just make sure to include the extra fields in your custom signup form.

    Read more about using the signup actions for:

    • email auth here
    • username & password auth here

    If you are using Wasp's Auth UI, you can customize the SignupForm component by passing the additionalFields prop to it. It can be either a list of extra fields or a render function.

    Using a List of Extra Fields​

    When you pass in a list of extra fields to the SignupForm, they are added to the form one by one, in the order you pass them in.

    Inside the list, there can be either objects or render functions (you can combine them):

    1. Objects are a simple way to describe new fields you need, but a bit less flexible than render functions.
    2. Render functions can be used to render any UI you want, but they require a bit more code. The render functions receive the react-hook-form object and the form state object as arguments.
    src/SignupPage.jsx
    import {
      SignupForm,
      FormError,
      FormInput,
      FormItemGroup,
      FormLabel,
    } from 'wasp/client/auth'

    export const SignupPage = () => {
      return (
        <SignupForm
          additionalFields={[
            /* The address field is defined using an object */
            {
              name: 'address',
              label: 'Address',
              type: 'input',
              validations: {
                required: 'Address is required',
              },
            },
            /* The phone number is defined using a render function */
            (form, state) => {
              return (
                <FormItemGroup>
                  <FormLabel>Phone Number</FormLabel>
                  <FormInput
                    {...form.register('phoneNumber', {
                      required: 'Phone number is required',
                    })}
                    disabled={state.isLoading}
                  />
                  {form.formState.errors.phoneNumber && (
                    <FormError>
                      {form.formState.errors.phoneNumber.message}
                    </FormError>
                  )}
                </FormItemGroup>
              )
            },
          ]}
        />
      )
    }

    Read more about the extra fields in the API Reference.

    Using a Single Render Function​

    Instead of passing in a list of extra fields, you can pass in a render function which will receive the react-hook-form object and the form state object as arguments. What ever the render function returns, will be rendered below the default fields.

    src/SignupPage.jsx
    import { SignupForm, FormItemGroup } from 'wasp/client/auth'

    export const SignupPage = () => {
      return (
        <SignupForm
          additionalFields={(form, state) => {
            const username = form.watch('username')
            return (
              username && (
                <FormItemGroup>
                  Hello there <strong>{username}</strong> 👋
                </FormItemGroup>
              )
            )
          }}
        />
      )
    }

    Read more about the render function in the API Reference.

    API Reference​

    Auth Fields​

    main.wasp
      title: "My app",
      //...
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {}, // use this or email, not both
          email: {}, // use this or usernameAndPassword, not both
          google: {},
          gitHub: {},
        },
        onAuthFailedRedirectTo: "/someRoute",
        signup: { ... }
      }
    }

    //...

    app.auth is a dictionary with the following fields:

    userEntity: entity required​

    The entity representing the user connected to your business logic.

    You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

    methods: dict required​

    A dictionary of auth methods enabled for the app.

    Email »

    Email verification, password reset, etc.

    Username & Password »

    The simplest way to get started

    Google »

    Users sign in with their Google account

    Github »

    Users sign in with their Github account

    Keycloak »

    Users sign in with their Keycloak account

    Click on each auth method for more details.

    onAuthFailedRedirectTo: String required​

    The route to which Wasp should redirect unauthenticated user when they try to access a private page (i.e., a page that has authRequired: true). Check out these essentials docs on auth to see an example of usage.

    onAuthSucceededRedirectTo: String​

    The route to which Wasp will send a successfully authenticated after a successful login/signup. The default value is "/".

    note

    Automatic redirect on successful login only works when using the Wasp-provided Auth UI.

    signup: SignupOptions​

    Read more about the signup process customization API in the Signup Fields Customization section.

    Signup Fields Customization​

    If you want to add extra fields to the signup process, the server needs to know how to save them to the database. You do that by defining the auth.methods.{authMethod}.userSignupFields field in your main.wasp file.

    main.wasp
    app crudTesting {
      // ...
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {
            userSignupFields: import { userSignupFields } from "@src/auth/signup",
          },
        },
        onAuthFailedRedirectTo: "/login",
      },
    }

    Then we'll export the userSignupFields object from the src/auth/signup.js file:

    src/auth/signup.js
    import { defineUserSignupFields } from 'wasp/server/auth'

    export const userSignupFields = defineUserSignupFields({
      address: async (data) => {
        const address = data.address
        if (typeof address !== 'string') {
          throw new Error('Address is required')
        }
        if (address.length < 5) {
          throw new Error('Address must be at least 5 characters long')
        }
        return address
      },
    })

    The userSignupFields object is an object where the keys represent the field name, and the values are functions that receive the data sent from the client* and return the value of the field.

    If the value that the function received is invalid, the function should throw an error.

    * We exclude the password field from this object to prevent it from being saved as plain text in the database. The password field is handled by Wasp's auth backend.

    SignupForm Customization​

    To customize the SignupForm component, you need to pass in the additionalFields prop. It can be either a list of extra fields or a render function.

    src/SignupPage.jsx
    import {
      SignupForm,
      FormError,
      FormInput,
      FormItemGroup,
      FormLabel,
    } from 'wasp/client/auth'

    export const SignupPage = () => {
      return (
        <SignupForm
          additionalFields={[
            {
              name: 'address',
              label: 'Address',
              type: 'input',
              validations: {
                required: 'Address is required',
              },
            },
            (form, state) => {
              return (
                <FormItemGroup>
                  <FormLabel>Phone Number</FormLabel>
                  <FormInput
                    {...form.register('phoneNumber', {
                      required: 'Phone number is required',
                    })}
                    disabled={state.isLoading}
                  />
                  {form.formState.errors.phoneNumber && (
                    <FormError>
                      {form.formState.errors.phoneNumber.message}
                    </FormError>
                  )}
                </FormItemGroup>
              )
            },
          ]}
        />
      )
    }

    The extra fields can be either objects or render functions (you can combine them):

    1. Objects are a simple way to describe new fields you need, but a bit less flexible than render functions.

      The objects have the following properties:

      • name required

        • the name of the field

      • label required

        • the label of the field (used in the UI)

      • type required

        • the type of the field, which can be input or textarea

      • validations

        • an object with the validation rules for the field. The keys are the validation names, and the values are the validation error messages. Read more about the available validation rules in the react-hook-form docs.

    2. Render functions receive the react-hook-form object and the form state as arguments, and they can use them to render arbitrary UI elements.

      The render function has the following signature:

      ;(form: UseFormReturn, state: FormState) => React.ReactNode

      • form required

        • the react-hook-form object, read more about it in the react-hook-form docs
        • you need to use the form.register function to register your fields

      • state required

        • the form state object which has the following properties:
          • isLoading: boolean
            • whether the form is currently submitting
    - - + + \ No newline at end of file diff --git a/docs/auth/social-auth/github.html b/docs/auth/social-auth/github.html index 477ac3db0a..c0b3f59aac 100644 --- a/docs/auth/social-auth/github.html +++ b/docs/auth/social-auth/github.html @@ -19,16 +19,16 @@ - - + + -
    -
    Version: 0.13.0

    GitHub

    Wasp supports Github Authentication out of the box. +

    +
    Version: 0.13.0

    GitHub

    Wasp supports Github Authentication out of the box. GitHub is a great external auth choice when you're building apps for developers, as most of them already have a GitHub account.

    Letting your users log in using their GitHub accounts turns the signup process into a breeze.

    Let's walk through enabling Github Authentication, explain some of the default settings, and show how to override them.

    Setting up Github Auth​

    Enabling GitHub Authentication comes down to a series of steps:

    1. Enabling GitHub authentication in the Wasp file.
    2. Adding the User entity.
    3. Creating a GitHub OAuth app.
    4. Adding the necessary Routes and Pages
    5. Using Auth UI components in our Pages.

    Here's a skeleton of how our main.wasp should look like after we're done:

    main.wasp
    // Configuring the social authentication
    app myApp {
      auth: { ... }
    }

    // Defining entities
    entity User { ... }

    // Defining routes and pages
    route LoginRoute { ... }
    page LoginPage { ... }

    1. Adding Github Auth to Your Wasp File​

    Let's start by properly configuring the Auth object:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the User entity  (we'll define it next)
        userEntity: User,
        methods: {
          // 2. Enable Github Auth
          gitHub: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    2. Add the User Entity​

    Let's now define the app.auth.userEntity entity:

    main.wasp
    // ...
    // 3. Define the User entity
    entity User {=psl
        id          Int     @id @default(autoincrement())
        // ...
    psl=}

    3. Creating a GitHub OAuth App​

    To use GitHub as an authentication method, you'll first need to create a GitHub OAuth App and provide Wasp with your client key and secret. Here's how you do it:

    1. Log into your GitHub account and navigate to: https://github.com/settings/developers.
    2. Select New OAuth App.
    3. Supply required information.
    GitHub Applications Screenshot
    • For Authorization callback URL:
      • For development, put: http://localhost:3001/auth/github/callback.
      • Once you know on which URL your API server will be deployed, you can create a new app with that URL instead e.g. https://your-server-url.com/auth/github/callback.
    1. Hit Register application.
    2. Hit Generate a new client secret on the next page.
    3. Copy your Client ID and Client secret as you'll need them in the next step.

    4. Adding Environment Variables​

    Add these environment variables to the .env.server file at the root of your project (take their values from the previous step):

    .env.server
    GITHUB_CLIENT_ID=your-github-client-id
    GITHUB_CLIENT_SECRET=your-github-client-secret

    5. Adding the Necessary Routes and Pages​

    Let's define the necessary authentication Routes and Pages.

    Add the following code to your main.wasp file:

    main.wasp
    // ...

    // 6. Define the routes
    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { Login } from "@src/pages/auth.jsx"
    }

    We'll define the React components for these pages in the src/pages/auth.tsx file below.

    6. Creating the Client Pages​

    info

    We are using Tailwind CSS to style the pages. Read more about how to add it here.

    Let's create a auth.tsx file in the src/pages folder and add the following to it:

    src/pages/auth.jsx
    import { LoginForm } from 'wasp/client/auth'

    export function Login() {
      return (
        <Layout>
          <LoginForm />
        </Layout>
      )
    }

    // A layout component to center the content
    export function Layout({ children }) {
      return (
        <div className="w-full h-full bg-white">
          <div className="min-w-full min-h-[75vh] flex items-center justify-center">
            <div className="w-full h-full max-w-sm p-5 bg-white">
              <div>{children}</div>
            </div>
          </div>
        </div>
      )
    }

    We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

    Conclusion​

    Yay, we've successfully set up Github Auth! 🎉

    Github Auth

    Running wasp db migrate-dev and wasp start should now give you a working app with authentication. To see how to protect specific pages (i.e., hide them from non-authenticated users), read the docs on using auth.

    Default Behaviour​

    Add gitHub: {} to the auth.methods dictionary to use it with default settings.

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          gitHub: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    When a user signs in for the first time, Wasp creates a new user account and links it to the chosen auth provider account for future logins.

    Overrides​

    By default, Wasp doesn't store any information it receives from the social login provider. It only stores the user's ID specific to the provider.

    There are two mechanisms used for overriding the default behavior:

    • userSignupFields
    • configFn

    Let's explore them in more detail.

    Data Received From GitHub​

    We are using GitHub's API and its /user and /user/emails endpoints to get the user data.

    We combine the data from the two endpoints

    You'll find the emails in the emails property in the object that you receive in userSignupFields.

    This is because we combine the data from the /user and /user/emails endpoints if the user or user:email scope is requested.

    The data we receive from GitHub on the /user endpoint looks something this:

    {
      "login": "octocat",
      "id": 1,
      "name": "monalisa octocat",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      // ...
    }

    And the data from the /user/emails endpoint looks something like this:

    [
      {
        "email": "octocat@github.com",
        "verified": true,
        "primary": true,
        "visibility": "public"
      }
    ]

    The fields you receive will depend on the scopes you requested. By default we don't specify any scopes. If you want to get the emails, you need to specify the user or user:email scope in the configFn function.

    For an up to date info about the data received from GitHub, please refer to the GitHub API documentation.

    Using the Data Received From GitHub​

    When a user logs in using a social login provider, the backend receives some data about the user. Wasp lets you access this data inside the userSignupFields getters.

    For example, the User entity can include a displayName field which you can set based on the details received from the provider.

    Wasp also lets you customize the configuration of the providers' settings using the configFn function.

    Let's use this example to show both fields in action:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          gitHub: {
            configFn: import { getConfig } from "@src/auth/github.js",
            userSignupFields: import { userSignupFields } from "@src/auth/github.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    entity User {=psl
        id                        Int     @id @default(autoincrement())
        username                  String  @unique
        displayName               String
    psl=}

    // ...
    src/auth/github.js
    export const userSignupFields = {
      username: () => "hardcoded-username",
      displayName: (data) => data.profile.name,
    };

    export function getConfig() {
      return {
        scopes: ['user'],
      };
    }

    Using Auth​

    To read more about how to set up the logout button and get access to the logged-in user in both client and server code, read the docs on using auth.

    API Reference​

    Provider-specific behavior comes down to implementing two functions.

    • configFn
    • userSignupFields

    The reference shows how to define both.

    For behavior common to all providers, check the general API Reference.

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          gitHub: {
            configFn: import { getConfig } from "@src/auth/github.js",
            userSignupFields: import { userSignupFields } from "@src/auth/github.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    The gitHub dict has the following properties:

    • configFn: ExtImport​

      This function should return an object with the scopes for the OAuth provider.

      src/auth/github.js
      export function getConfig() {
        return {
          scopes: [],
        }
      }

    • userSignupFields: ExtImport​

      userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

      src/auth.js
      import { defineUserSignupFields } from 'wasp/server/auth'

      export const userSignupFields = defineUserSignupFields({
        address: (data) => {
          if (!data.address) {
            throw new Error('Address is required')
          }
          return data.address
        }
        phone: (data) => data.phone,
      })

      Read more about the userSignupFields function here.

    - - + + \ No newline at end of file diff --git a/docs/auth/social-auth/google.html b/docs/auth/social-auth/google.html index 0f0034d844..1de2d25ca7 100644 --- a/docs/auth/social-auth/google.html +++ b/docs/auth/social-auth/google.html @@ -19,17 +19,17 @@ - - + + -
    -
    Version: 0.13.0

    Google

    Wasp supports Google Authentication out of the box. +

    +
    Version: 0.13.0

    Google

    Wasp supports Google Authentication out of the box. Google Auth is arguably the best external auth option, as most users on the web already have Google accounts.

    Enabling it lets your users log in using their existing Google accounts, greatly simplifying the process and enhancing the user experience.

    Let's walk through enabling Google authentication, explain some of the default settings, and show how to override them.

    Setting up Google Auth​

    Enabling Google Authentication comes down to a series of steps:

    1. Enabling Google authentication in the Wasp file.
    2. Adding the User entity.
    3. Creating a Google OAuth app.
    4. Adding the necessary Routes and Pages
    5. Using Auth UI components in our Pages.

    Here's a skeleton of how our main.wasp should look like after we're done:

    main.wasp
    // Configuring the social authentication
    app myApp {
      auth: { ... }
    }

    // Defining entities
    entity User { ... }

    // Defining routes and pages
    route LoginRoute { ... }
    page LoginPage { ... }

    1. Adding Google Auth to Your Wasp File​

    Let's start by properly configuring the Auth object:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the User entity (we'll define it next)
        userEntity: User,
        methods: {
          // 2. Enable Google Auth
          google: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    userEntity is explained in the social auth overview.

    2. Adding the User Entity​

    Let's now define the app.auth.userEntity entity:

    main.wasp
    // ...
    // 3. Define the User entity
    entity User {=psl
        id          Int     @id @default(autoincrement())
        // ...
    psl=}

    3. Creating a Google OAuth App​

    To use Google as an authentication method, you'll first need to create a Google project and provide Wasp with your client key and secret. Here's how you do it:

    1. Create a Google Cloud Platform account if you do not already have one: https://cloud.google.com/
    2. Create and configure a new Google project here: https://console.cloud.google.com/home/dashboard

    Google Console Screenshot 1

    Google Console Screenshot 2

    1. Search for OAuth in the top bar, click on OAuth consent screen.

    Google Console Screenshot 3

    • Select what type of app you want, we will go with External.

      Google Console Screenshot 4

    • Fill out applicable information on Page 1.

      Google Console Screenshot 5

    • On Page 2, Scopes, you should select userinfo.profile. You can optionally search for other things, like email.

      Google Console Screenshot 6

      Google Console Screenshot 7

      Google Console Screenshot 8

    • Add any test users you want on Page 3.

      Google Console Screenshot 9

    1. Next, click Credentials.

    Google Console Screenshot 10

    • Select Create Credentials.

    • Select OAuth client ID.

      Google Console Screenshot 11

    • Complete the form

      Google Console Screenshot 12

    • Under Authorized redirect URIs, put in: http://localhost:3001/auth/google/callback

      Google Console Screenshot 13

      • Once you know on which URL(s) your API server will be deployed, also add those URL(s).
        • For example: https://your-server-url.com/auth/google/callback

    • When you save, you can click the Edit icon and your credentials will be shown.

      Google Console Screenshot 14

    1. Copy your Client ID and Client secret as you will need them in the next step.

    4. Adding Environment Variables​

    Add these environment variables to the .env.server file at the root of your project (take their values from the previous step):

    .env.server
    GOOGLE_CLIENT_ID=your-google-client-id
    GOOGLE_CLIENT_SECRET=your-google-client-secret

    5. Adding the Necessary Routes and Pages​

    Let's define the necessary authentication Routes and Pages.

    Add the following code to your main.wasp file:

    main.wasp
    // ...

    // 6. Define the routes
    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { Login } from "@src/pages/auth.jsx"
    }

    We'll define the React components for these pages in the src/pages/auth.tsx file below.

    6. Create the Client Pages​

    info

    We are using Tailwind CSS to style the pages. Read more about how to add it here.

    Let's now create a auth.tsx file in the src/pages. It should have the following code:

    src/pages/auth.jsx
    import { LoginForm } from 'wasp/client/auth'

    export function Login() {
      return (
        <Layout>
          <LoginForm />
        </Layout>
      )
    }

    // A layout component to center the content
    export function Layout({ children }) {
      return (
        <div className="w-full h-full bg-white">
          <div className="min-w-full min-h-[75vh] flex items-center justify-center">
            <div className="w-full h-full max-w-sm p-5 bg-white">
              <div>{children}</div>
            </div>
          </div>
        </div>
      )
    }
    Auth UI

    Our pages use an automatically-generated Auth UI component. Read more about Auth UI components here.

    Conclusion​

    Yay, we've successfully set up Google Auth! 🎉

    Google Auth

    Running wasp db migrate-dev and wasp start should now give you a working app with authentication. To see how to protect specific pages (i.e., hide them from non-authenticated users), read the docs on using auth.

    Default Behaviour​

    Add google: {} to the auth.methods dictionary to use it with default settings:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          google: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    When a user signs in for the first time, Wasp creates a new user account and links it to the chosen auth provider account for future logins.

    Overrides​

    By default, Wasp doesn't store any information it receives from the social login provider. It only stores the user's ID specific to the provider.

    There are two mechanisms used for overriding the default behavior:

    • userSignupFields
    • configFn

    Let's explore them in more detail.

    Data Received From Google​

    We are using Google's API and its /userinfo endpoint to fetch the user's data.

    The data received from Google is an object which can contain the following fields:

    [
      "name",
      "given_name",
      "family_name",
      "email",
      "email_verified",
      "aud",
      "exp",
      "iat",
      "iss",
      "locale",
      "picture",
      "sub"
    ]

    The fields you receive depend on the scopes you request. The default scope is set to profile only. If you want to get the user's email, you need to specify the email scope in the configFn function.

    For an up to date info about the data received from Google, please refer to the Google API documentation.

    Using the Data Received From Google​

    When a user logs in using a social login provider, the backend receives some data about the user. Wasp lets you access this data inside the userSignupFields getters.

    For example, the User entity can include a displayName field which you can set based on the details received from the provider.

    Wasp also lets you customize the configuration of the providers' settings using the configFn function.

    Let's use this example to show both fields in action:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          google: {
            configFn: import { getConfig } from "@src/auth/google.js",
            userSignupFields: import { userSignupFields } from "@src/auth/google.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    entity User {=psl
        id                        Int     @id @default(autoincrement())
        username                  String  @unique
        displayName               String
    psl=}

    // ...
    src/auth/google.js
    export const userSignupFields = {
      username: () => "hardcoded-username",
      displayName: (data) => data.profile.name,
    }

    export function getConfig() {
      return {
        scopes: ['profile', 'email'],
      }
    }

    Using Auth​

    To read more about how to set up the logout button and get access to the logged-in user in both client and server code, read the docs on using auth.

    API Reference​

    Provider-specific behavior comes down to implementing two functions.

    • configFn
    • userSignupFields

    The reference shows how to define both.

    For behavior common to all providers, check the general API Reference.

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          google: {
            configFn: import { getConfig } from "@src/auth/google.js",
            userSignupFields: import { userSignupFields } from "@src/auth/google.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    The google dict has the following properties:

    • configFn: ExtImport​

      This function must return an object with the scopes for the OAuth provider.

      src/auth/google.js
      export function getConfig() {
        return {
          scopes: ['profile', 'email'],
        }
      }

    • userSignupFields: ExtImport​

      userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

      src/auth.js
      import { defineUserSignupFields } from 'wasp/server/auth'

      export const userSignupFields = defineUserSignupFields({
        address: (data) => {
          if (!data.address) {
            throw new Error('Address is required')
          }
          return data.address
        }
        phone: (data) => data.phone,
      })

      Read more about the userSignupFields function here.

    - - + + \ No newline at end of file diff --git a/docs/auth/social-auth/keycloak.html b/docs/auth/social-auth/keycloak.html index d262ddfb1e..aac1309076 100644 --- a/docs/auth/social-auth/keycloak.html +++ b/docs/auth/social-auth/keycloak.html @@ -19,16 +19,16 @@ - - + + -
    -
    Version: 0.13.0

    Keycloak

    Wasp supports Keycloak Authentication out of the box.

    Keycloak is an open-source identity and access management solution for modern applications and services. Keycloak provides both SAML and OpenID protocol solutions. It also has a very flexible and powerful administration UI.

    Let's walk through enabling Keycloak authentication, explain some of the default settings, and show how to override them.

    Setting up Keycloak Auth​

    Enabling Keycloak Authentication comes down to a series of steps:

    1. Enabling Keycloak authentication in the Wasp file.
    2. Adding the User entity.
    3. Creating a Keycloak client.
    4. Adding the necessary Routes and Pages
    5. Using Auth UI components in our Pages.

    Here's a skeleton of how our main.wasp should look like after we're done:

    main.wasp
    // Configuring the social authentication
    app myApp {
      auth: { ... }
    }

    // Defining entities
    entity User { ... }

    // Defining routes and pages
    route LoginRoute { ... }
    page LoginPage { ... }

    1. Adding Keycloak Auth to Your Wasp File​

    Let's start by properly configuring the Auth object:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the User entity (we'll define it next)
        userEntity: User,
        methods: {
          // 2. Enable Keycloak Auth
          keycloak: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    The userEntity is explained in the social auth overview.

    2. Adding the User Entity​

    Let's now define the app.auth.userEntity entity:

    main.wasp
    // ...
    // 3. Define the User entity
    entity User {=psl
        id          Int     @id @default(autoincrement())
        // ...
    psl=}

    3. Creating a Keycloak Client​

    1. Log into your Keycloak admin console.

    2. Under Clients, click on Create Client.

      Keycloak Screenshot 1

    3. Fill in the Client ID and choose a name for the client.

      Keycloak Screenshot 2

    4. In the next step, enable Client Authentication.

      Keycloak Screenshot 3

    5. Under Valid Redirect URIs, add http://localhost:3001/auth/keycloak/callback for local development.

      Keycloak Screenshot 4

      • Once you know on which URL(s) your API server will be deployed, also add those URL(s).
      • For example: https://my-server-url.com/auth/keycloak/callback.

    6. Click Save.

    7. In the Credentials tab, copy the Client Secret value, which we'll use in the next step.

      Keycloak Screenshot 5

    4. Adding Environment Variables​

    Add these environment variables to the .env.server file at the root of your project (take their values from the previous step):

    .env.server
    KEYCLOAK_CLIENT_ID=your-keycloak-client-id
    KEYCLOAK_CLIENT_SECRET=your-keycloak-client-secret
    KEYCLOAK_REALM_URL=https://your-keycloak-url.com/realms/master

    We assumed in the KEYCLOAK_REALM_URL env variable that you are using the master realm. If you are using a different realm, replace master with your realm name.

    5. Adding the Necessary Routes and Pages​

    Let's define the necessary authentication Routes and Pages.

    Add the following code to your main.wasp file:

    main.wasp
    // ...

    // 6. Define the routes
    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { Login } from "@src/pages/auth.jsx"
    }

    We'll define the React components for these pages in the src/pages/auth.tsx file below.

    6. Create the Client Pages​

    info

    We are using Tailwind CSS to style the pages. Read more about how to add it here.

    Let's now create an auth.tsx file in the src/pages. +

    +
    Version: 0.13.0

    Keycloak

    Wasp supports Keycloak Authentication out of the box.

    Keycloak is an open-source identity and access management solution for modern applications and services. Keycloak provides both SAML and OpenID protocol solutions. It also has a very flexible and powerful administration UI.

    Let's walk through enabling Keycloak authentication, explain some of the default settings, and show how to override them.

    Setting up Keycloak Auth​

    Enabling Keycloak Authentication comes down to a series of steps:

    1. Enabling Keycloak authentication in the Wasp file.
    2. Adding the User entity.
    3. Creating a Keycloak client.
    4. Adding the necessary Routes and Pages
    5. Using Auth UI components in our Pages.

    Here's a skeleton of how our main.wasp should look like after we're done:

    main.wasp
    // Configuring the social authentication
    app myApp {
      auth: { ... }
    }

    // Defining entities
    entity User { ... }

    // Defining routes and pages
    route LoginRoute { ... }
    page LoginPage { ... }

    1. Adding Keycloak Auth to Your Wasp File​

    Let's start by properly configuring the Auth object:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the User entity (we'll define it next)
        userEntity: User,
        methods: {
          // 2. Enable Keycloak Auth
          keycloak: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    The userEntity is explained in the social auth overview.

    2. Adding the User Entity​

    Let's now define the app.auth.userEntity entity:

    main.wasp
    // ...
    // 3. Define the User entity
    entity User {=psl
        id          Int     @id @default(autoincrement())
        // ...
    psl=}

    3. Creating a Keycloak Client​

    1. Log into your Keycloak admin console.

    2. Under Clients, click on Create Client.

      Keycloak Screenshot 1

    3. Fill in the Client ID and choose a name for the client.

      Keycloak Screenshot 2

    4. In the next step, enable Client Authentication.

      Keycloak Screenshot 3

    5. Under Valid Redirect URIs, add http://localhost:3001/auth/keycloak/callback for local development.

      Keycloak Screenshot 4

      • Once you know on which URL(s) your API server will be deployed, also add those URL(s).
      • For example: https://my-server-url.com/auth/keycloak/callback.

    6. Click Save.

    7. In the Credentials tab, copy the Client Secret value, which we'll use in the next step.

      Keycloak Screenshot 5

    4. Adding Environment Variables​

    Add these environment variables to the .env.server file at the root of your project (take their values from the previous step):

    .env.server
    KEYCLOAK_CLIENT_ID=your-keycloak-client-id
    KEYCLOAK_CLIENT_SECRET=your-keycloak-client-secret
    KEYCLOAK_REALM_URL=https://your-keycloak-url.com/realms/master

    We assumed in the KEYCLOAK_REALM_URL env variable that you are using the master realm. If you are using a different realm, replace master with your realm name.

    5. Adding the Necessary Routes and Pages​

    Let's define the necessary authentication Routes and Pages.

    Add the following code to your main.wasp file:

    main.wasp
    // ...

    // 6. Define the routes
    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { Login } from "@src/pages/auth.jsx"
    }

    We'll define the React components for these pages in the src/pages/auth.tsx file below.

    6. Create the Client Pages​

    info

    We are using Tailwind CSS to style the pages. Read more about how to add it here.

    Let's now create an auth.tsx file in the src/pages. It should have the following code:

    src/pages/auth.jsx
    import { LoginForm } from 'wasp/client/auth'

    export function Login() {
      return (
        <Layout>
          <LoginForm />
        </Layout>
      )
    }

    // A layout component to center the content
    export function Layout({ children }) {
      return (
        <div className="w-full h-full bg-white">
          <div className="min-w-full min-h-[75vh] flex items-center justify-center">
            <div className="w-full h-full max-w-sm p-5 bg-white">
              <div>{children}</div>
            </div>
          </div>
        </div>
      )
    }
    Auth UI

    Our pages use an automatically generated Auth UI component. Read more about Auth UI components here.

    Conclusion​

    Yay, we've successfully set up Keycloak Auth!

    Running wasp db migrate-dev and wasp start should now give you a working app with authentication. To see how to protect specific pages (i.e., hide them from non-authenticated users), read the docs on using auth.

    Default Behaviour​

    Add keycloak: {} to the auth.methods dictionary to use it with default settings:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          keycloak: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    When a user signs in for the first time, Wasp creates a new user account and links it to the chosen auth provider account for future logins.

    Overrides​

    By default, Wasp doesn't store any information it receives from the social login provider. It only stores the user's ID specific to the provider.

    There are two mechanisms used for overriding the default behavior:

    • userSignupFields
    • configFn

    Let's explore them in more detail.

    Data Received From Keycloak​

    We are using Keycloak's API and its /userinfo endpoint to fetch the user's data.

    Keycloak user data
    {
      sub: '5adba8fc-3ea6-445a-a379-13f0bb0b6969',
      email_verified: true,
      name: 'Test User',
      preferred_username: 'test',
      given_name: 'Test',
      family_name: 'User',
      email: 'test@example.com'
    }

    The fields you receive will depend on the scopes you requested. The default scope is set to profile only. If you want to get the user's email, you need to specify the email scope in the configFn function.

    For up-to-date info about the data received from Keycloak, please refer to the Keycloak API documentation.

    Using the Data Received From Keycloak​

    When a user logs in using a social login provider, the backend receives some data about the user. Wasp lets you access this data inside the userSignupFields getters.

    For example, the User entity can include a displayName field which you can set based on the details received from the provider.

    Wasp also lets you customize the configuration of the providers' settings using the configFn function.

    Let's use this example to show both fields in action:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          keycloak: {
            configFn: import { getConfig } from "@src/auth/keycloak.js",
            userSignupFields: import { userSignupFields } from "@src/auth/keycloak.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    entity User {=psl
        id                        Int     @id @default(autoincrement())
        username                  String  @unique
        displayName               String
    psl=}

    // ...
    src/auth/keycloak.js
    export const userSignupFields = {
      username: () => "hardcoded-username",
      displayName: (data) => data.profile.name,
    }

    export function getConfig() {
      return {
        scopes: ['profile', 'email'],
      }
    }

    Using Auth​

    To read more about how to set up the logout button and get access to the logged-in user in both client and server code, read the docs on using auth.

    API Reference​

    Provider-specific behavior comes down to implementing two functions.

    • configFn
    • userSignupFields

    The reference shows how to define both.

    For behavior common to all providers, check the general API Reference.

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          keycloak: {
            configFn: import { getConfig } from "@src/auth/keycloak.js",
            userSignupFields: import { userSignupFields } from "@src/auth/keycloak.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    The keycloak dict has the following properties:

    • configFn: ExtImport​

      This function must return an object with the scopes for the OAuth provider.

      src/auth/keycloak.js
      export function getConfig() {
        return {
          scopes: ['profile', 'email'],
        }
      }

    • userSignupFields: ExtImport​

      userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

      src/auth.js
      import { defineUserSignupFields } from 'wasp/server/auth'

      export const userSignupFields = defineUserSignupFields({
        address: (data) => {
          if (!data.address) {
            throw new Error('Address is required')
          }
          return data.address
        }
        phone: (data) => data.phone,
      })

      Read more about the userSignupFields function here.

    - - + + \ No newline at end of file diff --git a/docs/auth/social-auth/overview.html b/docs/auth/social-auth/overview.html index b9fc2650dd..90ce97c77d 100644 --- a/docs/auth/social-auth/overview.html +++ b/docs/auth/social-auth/overview.html @@ -19,19 +19,19 @@ - - + + -
    -
    Version: 0.13.0

    Overview

    Social login options (e.g., Log in with Google) are a great (maybe even the best) solution for handling user accounts. +

    +
    Version: 0.13.0

    Overview

    Social login options (e.g., Log in with Google) are a great (maybe even the best) solution for handling user accounts. A famous old developer joke tells us "The best auth system is the one you never have to make."

    Wasp wants to make adding social login options to your app as painless as possible.

    Using different social providers gives users a chance to sign into your app via their existing accounts on other platforms (Google, GitHub, etc.).

    This page goes through the common behaviors between all supported social login providers and shows you how to customize them. It also gives an overview of Wasp's UI helpers - the quickest possible way to get started with social auth.

    Available Providers​

    Wasp currently supports the following social login providers:

    User Entity​

    Wasp requires you to declare a userEntity for all auth methods (social or otherwise). This field tells Wasp which Entity represents the user.

    Here's what the full setup looks like:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          google: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    entity User {=psl
        id                        Int           @id @default(autoincrement())
        //...
    psl=}

    To learn more about what the fields on these entities represent, look at the API Reference.

    Default Behavior​

    When a user signs in for the first time, Wasp creates a new user account and links it to the chosen auth provider account for future logins.

    Overrides​

    By default, Wasp doesn't store any information it receives from the social login provider. It only stores the user's ID specific to the provider.

    If you wish to store more information about the user, you can override the default behavior. You can do this by defining the userSignupFields and configFn fields in main.wasp for each provider.

    You can create custom signup setups, such as allowing users to define a custom username after they sign up with a social provider.

    Example: Allowing User to Set Their Username​

    If you want to modify the signup flow (e.g., let users choose their own usernames), you will need to go through three steps:

    1. The first step is adding a isSignupComplete property to your User Entity. This field will signal whether the user has completed the signup process.
    2. The second step is overriding the default signup behavior.
    3. The third step is implementing the rest of your signup flow and redirecting users where appropriate.

    Let's go through both steps in more detail.

    1. Adding the isSignupComplete Field to the User Entity​

    main.wasp
    entity User {=psl
        id                        Int           @id @default(autoincrement())
        username                  String?       @unique
        isSignupComplete          Boolean       @default(false)
    psl=}

    2. Overriding the Default Behavior​

    Declare an import under app.auth.methods.google.userSignupFields (the example assumes you're using Google):

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          google: {
            userSignupFields: import { userSignupFields } from "@src/auth/google.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    // ...

    And implement the imported function.

    src/auth/google.js
    export const userSignupFields = {
      isSignupComplete: () => false,
    }

    3. Showing the Correct State on the Client​

    You can query the user's isSignupComplete flag on the client with the useAuth() hook. Depending on the flag's value, you can redirect users to the appropriate signup step.

    For example:

    1. When the user lands on the homepage, check the value of user.isSignupComplete.
    2. If it's false, it means the user has started the signup process but hasn't yet chosen their username. Therefore, you can redirect them to EditUserDetailsPage where they can edit the username property.
    src/HomePage.jsx
    import { useAuth } from 'wasp/client/auth'
    import { Redirect } from 'react-router-dom'

    export function HomePage() {
      const { data: user } = useAuth()

      if (user.isSignupComplete === false) {
        return <Redirect to="/edit-user-details" />
      }

      // ...
    }

    Using the User's Provider Account Details​

    Account details are provider-specific. Each provider has their own rules for defining the userSignupFields and configFn fields:

    UI Helpers​

    Use Auth UI

    Auth UI is a common name for all high-level auth forms that come with Wasp.

    These include fully functional auto-generated login and signup forms with working social login buttons. If you're looking for the fastest way to get your auth up and running, that's where you should look.

    The UI helpers described below are lower-level and are useful for creating your custom forms.

    Wasp provides sign-in buttons and URLs for each of the supported social login providers.

    src/LoginPage.jsx
    import {
      GoogleSignInButton,
      googleSignInUrl,
      GitHubSignInButton,
      gitHubSignInUrl,
    } from 'wasp/client/auth'

    export const LoginPage = () => {
      return (
        <>
          <GoogleSignInButton />
          <GitHubSignInButton />
          {/* or */}
          <a href={googleSignInUrl}>Sign in with Google</a>
          <a href={gitHubSignInUrl}>Sign in with GitHub</a>
        </>
      )
    }

    If you need even more customization, you can create your custom components using signInUrls.

    API Reference​

    Fields in the app.auth Dictionary and Overrides​

    For more information on:

    • Allowed fields in app.auth
    • userSignupFields and configFn functions

    Check the provider-specific API References:

    - - + + \ No newline at end of file diff --git a/docs/auth/ui.html b/docs/auth/ui.html index 21e0ab25d0..fe071fce75 100644 --- a/docs/auth/ui.html +++ b/docs/auth/ui.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Auth UI

    To make using authentication in your app as easy as possible, Wasp generates the server-side code but also the client-side UI for you. It enables you to quickly get the login, signup, password reset and email verification flows in your app.

    Below we cover all of the available UI components and how to use them.

    Auth UI

    Overview​

    After Wasp generates the UI components for your auth, you can use it as is, or customize it to your liking.

    Based on the authentication providers you enabled in your main.wasp file, the Auth UI will show the corresponding UI (form and buttons). For example, if you enabled e-mail authentication:

    main.wasp
    app MyApp {
      //...
      auth: {
        methods: {
          email: {},
        },
        // ...
      }
    }

    You'll get the following UI:

    Auth UI

    And then if you enable Google and Github:

    main.wasp
    app MyApp {
      //...
      auth: {
        methods: {
          email: {},
          google: {},
          github: {},
        },
        // ...
      }
    }

    The form will automatically update to look like this:

    Auth UI

    Let's go through all of the available components and how to use them.

    Auth Components​

    The following components are available for you to use in your app:

    Login Form​

    Used with Username & Password, Email, Github, Google and Keycloak authentication.

    Login form

    You can use the LoginForm component to build your login page:

    main.wasp
    // ...

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage.jsx"
    }
    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'

    // Use it like this
    export function LoginPage() {
      return <LoginForm />
    }

    It will automatically show the correct authentication providers based on your main.wasp file.

    Signup Form​

    Used with Username & Password, Email, Github, Google and Keycloak authentication.

    Signup form

    You can use the SignupForm component to build your signup page:

    main.wasp
    // ...

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage.jsx"
    }
    src/SignupPage.jsx
    import { SignupForm } from 'wasp/client/auth'

    // Use it like this
    export function SignupPage() {
      return <SignupForm />
    }

    It will automatically show the correct authentication providers based on your main.wasp file.

    Read more about customizing the signup process like adding additional fields or extra UI in the Auth Overview section.

    Forgot Password Form​

    Used with Email authentication.

    If users forget their password, they can use this form to reset it.

    Forgot password form

    You can use the ForgotPasswordForm component to build your own forgot password page:

    main.wasp
    // ...

    route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
    page RequestPasswordResetPage {
      component: import { ForgotPasswordPage } from "@src/ForgotPasswordPage.jsx"
    }
    src/ForgotPasswordPage.jsx
    import { ForgotPasswordForm } from 'wasp/client/auth'

    // Use it like this
    export function ForgotPasswordPage() {
      return <ForgotPasswordForm />
    }

    Reset Password Form​

    Used with Email authentication.

    After users click on the link in the email they receive after submitting the forgot password form, they will be redirected to this form where they can reset their password.

    Reset password form

    You can use the ResetPasswordForm component to build your reset password page:

    main.wasp
    // ...

    route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
    page PasswordResetPage {
      component: import { ResetPasswordPage } from "@src/ResetPasswordPage.jsx"
    }
    src/ResetPasswordPage.jsx
    import { ResetPasswordForm } from 'wasp/client/auth'

    // Use it like this
    export function ResetPasswordPage() {
      return <ResetPasswordForm />
    }

    Verify Email Form​

    Used with Email authentication.

    After users sign up, they will receive an email with a link to this form where they can verify their email.

    Verify email form

    You can use the VerifyEmailForm component to build your email verification page:

    main.wasp
    // ...

    route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
    page EmailVerificationPage {
      component: import { VerifyEmailPage } from "@src/VerifyEmailPage.jsx"
    }
    src/VerifyEmailPage.jsx
    import { VerifyEmailForm } from 'wasp/client/auth'

    // Use it like this
    export function VerifyEmailPage() {
      return <VerifyEmailForm />
    }

    Customization 💅🏻​

    You customize all of the available forms by passing props to them.

    Props you can pass to all of the forms:

    1. appearance - customize the form colors (via design tokens)
    2. logo - path to your logo
    3. socialLayout - layout of the social buttons, which can be vertical or horizontal

    1. Customizing the Colors​

    We use Stitches to style the Auth UI. You can customize the styles by overriding the default theme tokens.

    List of all available tokens

    See the list of all available tokens which you can override.

    src/appearance.js
    export const authAppearance = {
      colors: {
        brand: '#5969b8', // blue
        brandAccent: '#de5998', // pink
        submitButtonText: 'white',
      },
    }
    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'
    import { authAppearance } from './appearance'

    export function LoginPage() {
      return (
        <LoginForm
          // Pass the appearance object to the form
          appearance={authAppearance}
        />
      )
    }

    We recommend defining your appearance in a separate file and importing it into your components.

    You can add your logo to the Auth UI by passing the logo prop to any of the components.

    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'
    import Logo from './logo.png'

    export function LoginPage() {
      return (
        <LoginForm
          // Pass in the path to your logo
          logo={Logo}
        />
      )
    }

    3. Social Buttons Layout​

    You can change the layout of the social buttons by passing the socialLayout prop to any of the components. It can be either vertical or horizontal (default).

    If we pass in vertical:

    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'

    export function LoginPage() {
      return (
        <LoginForm
          // Pass in the socialLayout prop
          socialLayout="vertical"
        />
      )
    }

    We get this:

    Vertical social buttons

    Let's Put Everything Together 🪄​

    If we provide the logo and custom colors:

    src/appearance.js
    export const appearance = {
      colors: {
        brand: '#5969b8', // blue
        brandAccent: '#de5998', // pink
        submitButtonText: 'white',
      },
    }
    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'

    import { authAppearance } from './appearance'
    import todoLogo from './todoLogo.png'

    export function LoginPage() {
      return <LoginForm appearance={appearance} logo={todoLogo} />
    }

    We get a form looking like this:

    Custom login form
    - - +
    +
    Version: 0.13.0

    Auth UI

    To make using authentication in your app as easy as possible, Wasp generates the server-side code but also the client-side UI for you. It enables you to quickly get the login, signup, password reset and email verification flows in your app.

    Below we cover all of the available UI components and how to use them.

    Auth UI

    Overview​

    After Wasp generates the UI components for your auth, you can use it as is, or customize it to your liking.

    Based on the authentication providers you enabled in your main.wasp file, the Auth UI will show the corresponding UI (form and buttons). For example, if you enabled e-mail authentication:

    main.wasp
    app MyApp {
      //...
      auth: {
        methods: {
          email: {},
        },
        // ...
      }
    }

    You'll get the following UI:

    Auth UI

    And then if you enable Google and Github:

    main.wasp
    app MyApp {
      //...
      auth: {
        methods: {
          email: {},
          google: {},
          github: {},
        },
        // ...
      }
    }

    The form will automatically update to look like this:

    Auth UI

    Let's go through all of the available components and how to use them.

    Auth Components​

    The following components are available for you to use in your app:

    Login Form​

    Used with Username & Password, Email, Github, Google and Keycloak authentication.

    Login form

    You can use the LoginForm component to build your login page:

    main.wasp
    // ...

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage.jsx"
    }
    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'

    // Use it like this
    export function LoginPage() {
      return <LoginForm />
    }

    It will automatically show the correct authentication providers based on your main.wasp file.

    Signup Form​

    Used with Username & Password, Email, Github, Google and Keycloak authentication.

    Signup form

    You can use the SignupForm component to build your signup page:

    main.wasp
    // ...

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage.jsx"
    }
    src/SignupPage.jsx
    import { SignupForm } from 'wasp/client/auth'

    // Use it like this
    export function SignupPage() {
      return <SignupForm />
    }

    It will automatically show the correct authentication providers based on your main.wasp file.

    Read more about customizing the signup process like adding additional fields or extra UI in the Auth Overview section.

    Forgot Password Form​

    Used with Email authentication.

    If users forget their password, they can use this form to reset it.

    Forgot password form

    You can use the ForgotPasswordForm component to build your own forgot password page:

    main.wasp
    // ...

    route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
    page RequestPasswordResetPage {
      component: import { ForgotPasswordPage } from "@src/ForgotPasswordPage.jsx"
    }
    src/ForgotPasswordPage.jsx
    import { ForgotPasswordForm } from 'wasp/client/auth'

    // Use it like this
    export function ForgotPasswordPage() {
      return <ForgotPasswordForm />
    }

    Reset Password Form​

    Used with Email authentication.

    After users click on the link in the email they receive after submitting the forgot password form, they will be redirected to this form where they can reset their password.

    Reset password form

    You can use the ResetPasswordForm component to build your reset password page:

    main.wasp
    // ...

    route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
    page PasswordResetPage {
      component: import { ResetPasswordPage } from "@src/ResetPasswordPage.jsx"
    }
    src/ResetPasswordPage.jsx
    import { ResetPasswordForm } from 'wasp/client/auth'

    // Use it like this
    export function ResetPasswordPage() {
      return <ResetPasswordForm />
    }

    Verify Email Form​

    Used with Email authentication.

    After users sign up, they will receive an email with a link to this form where they can verify their email.

    Verify email form

    You can use the VerifyEmailForm component to build your email verification page:

    main.wasp
    // ...

    route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
    page EmailVerificationPage {
      component: import { VerifyEmailPage } from "@src/VerifyEmailPage.jsx"
    }
    src/VerifyEmailPage.jsx
    import { VerifyEmailForm } from 'wasp/client/auth'

    // Use it like this
    export function VerifyEmailPage() {
      return <VerifyEmailForm />
    }

    Customization 💅🏻​

    You customize all of the available forms by passing props to them.

    Props you can pass to all of the forms:

    1. appearance - customize the form colors (via design tokens)
    2. logo - path to your logo
    3. socialLayout - layout of the social buttons, which can be vertical or horizontal

    1. Customizing the Colors​

    We use Stitches to style the Auth UI. You can customize the styles by overriding the default theme tokens.

    List of all available tokens

    See the list of all available tokens which you can override.

    src/appearance.js
    export const authAppearance = {
      colors: {
        brand: '#5969b8', // blue
        brandAccent: '#de5998', // pink
        submitButtonText: 'white',
      },
    }
    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'
    import { authAppearance } from './appearance'

    export function LoginPage() {
      return (
        <LoginForm
          // Pass the appearance object to the form
          appearance={authAppearance}
        />
      )
    }

    We recommend defining your appearance in a separate file and importing it into your components.

    You can add your logo to the Auth UI by passing the logo prop to any of the components.

    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'
    import Logo from './logo.png'

    export function LoginPage() {
      return (
        <LoginForm
          // Pass in the path to your logo
          logo={Logo}
        />
      )
    }

    3. Social Buttons Layout​

    You can change the layout of the social buttons by passing the socialLayout prop to any of the components. It can be either vertical or horizontal (default).

    If we pass in vertical:

    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'

    export function LoginPage() {
      return (
        <LoginForm
          // Pass in the socialLayout prop
          socialLayout="vertical"
        />
      )
    }

    We get this:

    Vertical social buttons

    Let's Put Everything Together 🪄​

    If we provide the logo and custom colors:

    src/appearance.js
    export const appearance = {
      colors: {
        brand: '#5969b8', // blue
        brandAccent: '#de5998', // pink
        submitButtonText: 'white',
      },
    }
    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'

    import { authAppearance } from './appearance'
    import todoLogo from './todoLogo.png'

    export function LoginPage() {
      return <LoginForm appearance={appearance} logo={todoLogo} />
    }

    We get a form looking like this:

    Custom login form
    + + \ No newline at end of file diff --git a/docs/auth/username-and-pass.html b/docs/auth/username-and-pass.html index 65224260d6..2b6308642f 100644 --- a/docs/auth/username-and-pass.html +++ b/docs/auth/username-and-pass.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Username & Password

    Wasp supports username & password authentication out of the box with login and signup flows. It provides you with the server-side implementation and the UI components for the client-side.

    Setting Up Username & Password Authentication​

    To set up username authentication we need to:

    1. Enable username authentication in the Wasp file
    2. Add the User entity
    3. Add the auth routes and pages
    4. Use Auth UI components in our pages

    Structure of the main.wasp file we will end up with:

    main.wasp
    // Configuring e-mail authentication
    app myApp {
      auth: { ... }
    }
    // Defining User entity
    entity User { ... }
    // Defining routes and pages
    route SignupRoute { ... }
    page SignupPage { ... }
    // ...

    1. Enable Username Authentication​

    Let's start with adding the following to our main.wasp file:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the user entity (we'll define it next)
        userEntity: User,
        methods: {
          // 2. Enable username authentication
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login"
      }
    }

    Read more about the usernameAndPassword auth method options here.

    2. Add the User Entity​

    The User entity can be as simple as including only the id field:

    main.wasp
    // 3. Define the user entity
    entity User {=psl
        id                        Int           @id @default(autoincrement())
        // Add your own fields below
        // ...
    psl=}

    You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

    3. Add the Routes and Pages​

    Next, we need to define the routes and pages for the authentication pages.

    Add the following to the main.wasp file:

    main.wasp
    // ...
    // 4. Define the routes
    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { Login } from "@src/pages/auth.jsx"
    }
    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { Signup } from "@src/pages/auth.jsx"
    }

    We'll define the React components for these pages in the src/pages/auth.tsx file below.

    4. Create the Client Pages​

    info

    We are using Tailwind CSS to style the pages. Read more about how to add it here.

    Let's create a auth.tsx file in the src/pages folder and add the following to it:

    src/pages/auth.jsx
    import { LoginForm, SignupForm } from 'wasp/client/auth'
    import { Link } from 'react-router-dom'

    export function Login() {
      return (
        <Layout>
          <LoginForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            Don't have an account yet? <Link to="/signup">go to signup</Link>.
          </span>
        </Layout>
      );
    }

    export function Signup() {
      return (
        <Layout>
          <SignupForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            I already have an account (<Link to="/login">go to login</Link>).
          </span>
        </Layout>
      );
    }

    // A layout component to center the content
    export function Layout({ children }) {
      return (
        <div className="w-full h-full bg-white">
          <div className="min-w-full min-h-[75vh] flex items-center justify-center">
            <div className="w-full h-full max-w-sm p-5 bg-white">
              <div>{children}</div>
            </div>
          </div>
        </div>
      );
    }

    We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

    Conclusion​

    That's it! We have set up username authentication in our app. 🎉

    Running wasp db migrate-dev and then wasp start should give you a working app with username authentication. If you want to put some of the pages behind authentication, read the auth overview docs.

    Using multiple auth identities for a single user

    Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

    Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

    Customizing the Auth Flow​

    The login and signup flows are pretty standard: they allow the user to sign up and then log in with their username and password. The signup flow validates the username and password and then creates a new user entity in the database.

    Read more about the default username and password validation rules in the auth overview docs.

    If you require more control in your authentication flow, you can achieve that in the following ways:

    1. Create your UI and use signup and login actions.
    2. Create your custom sign-up action which uses the lower-level API, along with your custom code.

    1. Using the signup and login actions​

    login()​

    An action for logging in the user.

    It takes two arguments:

    • username: string required

      Username of the user logging in.

    • password: string required

      Password of the user logging in.

    You can use it like this:

    src/pages/auth.jsx
    import { login } from 'wasp/client/auth'

    import { useState } from 'react'
    import { useHistory, Link } from 'react-router-dom'

    export function LoginPage() {
      const [username, setUsername] = useState('')
      const [password, setPassword] = useState('')
      const [error, setError] = useState(null)
      const history = useHistory()

      async function handleSubmit(event) {
        event.preventDefault()
        try {
          await login(username, password)
          history.push('/')
        } catch (error) {
          setError(error)
        }
      }

      return (
        <form onSubmit={handleSubmit}>
          {/* ... */}
        </form>
      );
    }
    note

    When using the exposed login() function, make sure to implement your redirect on success login logic (e.g. redirecting to home).

    signup()​

    An action for signing up the user. This action does not log in the user, you still need to call login().

    It takes one argument:

    • userFields: object required

      It has the following fields:

      • username: string required

      • password: string required

      info

      By default, Wasp will only save the username and password fields. If you want to add extra fields to your signup process, read about defining extra signup fields.

    You can use it like this:

    src/pages/auth.jsx
    import { signup, login } from 'wasp/client/auth'

    import { useState } from 'react'
    import { useHistory } from 'react-router-dom'
    import { Link } from 'react-router-dom'

    export function Signup() {
      const [username, setUsername] = useState('')
      const [password, setPassword] = useState('')
      const [error, setError] = useState(null)
      const history = useHistory()

      async function handleSubmit(event) {
        event.preventDefault()
        try {
          await signup({
            username,
            password,
          })
          await login(username, password)
          history.push("/")
        } catch (error) {
          setError(error)
        }
      }

      return (
        <form onSubmit={handleSubmit}>
          {/* ... */}
        </form>
      );
    }

    2. Creating your custom sign-up action​

    The code of your custom sign-up action can look like this:

    main.wasp
    // ...

    action customSignup {
      fn: import { signup } from "@src/auth/signup.js",
    }
    src/auth/signup.js
    import {
      ensurePasswordIsPresent,
      ensureValidPassword,
      ensureValidUsername,
      createProviderId,
      sanitizeAndSerializeProviderData,
      createUser,
    } from 'wasp/server/auth'

    export const signup = async (args, _context) => {
      ensureValidUsername(args)
      ensurePasswordIsPresent(args)
      ensureValidPassword(args)

      try {
        const providerId = createProviderId('username', args.username)
        const providerData = await sanitizeAndSerializeProviderData({
          hashedPassword: args.password,
        })

        await createUser(
          providerId,
          providerData,
          // Any additional data you want to store on the User entity
          {},
        )
      } catch (e) {
        return {
          success: false,
          message: e.message,
        }
      }

      // Your custom code after sign-up.
      // ...

      return {
        success: true,
        message: 'User created successfully',
      }
    }

    We suggest using the built-in field validators for your authentication flow. You can import them from wasp/server/auth. These are the same validators that Wasp uses internally for the default authentication flow.

    Username​

    • ensureValidUsername(args)

      Checks if the username is valid and throws an error if it's not. Read more about the validation rules here.

    Password​

    • ensurePasswordIsPresent(args)

      Checks if the password is present and throws an error if it's not.

    • ensureValidPassword(args)

      Checks if the password is valid and throws an error if it's not. Read more about the validation rules here.

    Using Auth​

    To read more about how to set up the logout button and how to get access to the logged-in user in our client and server code, read the auth overview docs.

    getUsername​

    If you are looking to access the user's username in your code, you can do that by accessing the info about the user that is stored in the user.auth.identities array.

    To make things a bit easier for you, Wasp offers the getUsername helper.

    The getUsername helper returns the user's username or null if the user doesn't have a username auth identity.

    src/MainPage.jsx
    import { getUsername } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const username = getUsername(user)
      // ...
    }
    src/tasks.js
    import { getUsername } from 'wasp/auth'

    export const createTask = async (args, context) => {
      const username = getUsername(context.user)
      // ...
    }

    API Reference​

    userEntity fields​

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login"
      }
    }

    entity User {=psl
        id                        Int           @id @default(autoincrement())
    psl=}

    The user entity needs to have the following fields:

    • id required

      It can be of any type, but it needs to be marked with @id

    You can add any other fields you want to the user entity. Make sure to also define them in the userSignupFields field if they need to be set during the sign-up process.

    Fields in the usernameAndPassword dict​

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {
            userSignupFields: import { userSignupFields } from "@src/auth/email.js",
          },
        },
        onAuthFailedRedirectTo: "/login"
      }
    }
    // ...

    userSignupFields: ExtImport​

    userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

    src/auth.js
    import { defineUserSignupFields } from 'wasp/server/auth'

    export const userSignupFields = defineUserSignupFields({
      address: (data) => {
        if (!data.address) {
          throw new Error('Address is required')
        }
        return data.address
      }
      phone: (data) => data.phone,
    })
    Read more about the `userSignupFields` function [here](./overview#1-defining-extra-fields).
    - - +
    +
    Version: 0.13.0

    Username & Password

    Wasp supports username & password authentication out of the box with login and signup flows. It provides you with the server-side implementation and the UI components for the client-side.

    Setting Up Username & Password Authentication​

    To set up username authentication we need to:

    1. Enable username authentication in the Wasp file
    2. Add the User entity
    3. Add the auth routes and pages
    4. Use Auth UI components in our pages

    Structure of the main.wasp file we will end up with:

    main.wasp
    // Configuring e-mail authentication
    app myApp {
      auth: { ... }
    }
    // Defining User entity
    entity User { ... }
    // Defining routes and pages
    route SignupRoute { ... }
    page SignupPage { ... }
    // ...

    1. Enable Username Authentication​

    Let's start with adding the following to our main.wasp file:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the user entity (we'll define it next)
        userEntity: User,
        methods: {
          // 2. Enable username authentication
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login"
      }
    }

    Read more about the usernameAndPassword auth method options here.

    2. Add the User Entity​

    The User entity can be as simple as including only the id field:

    main.wasp
    // 3. Define the user entity
    entity User {=psl
        id                        Int           @id @default(autoincrement())
        // Add your own fields below
        // ...
    psl=}

    You can read more about how the User entity is connected to the rest of the auth system in the Auth Entities section of the docs.

    3. Add the Routes and Pages​

    Next, we need to define the routes and pages for the authentication pages.

    Add the following to the main.wasp file:

    main.wasp
    // ...
    // 4. Define the routes
    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { Login } from "@src/pages/auth.jsx"
    }
    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { Signup } from "@src/pages/auth.jsx"
    }

    We'll define the React components for these pages in the src/pages/auth.tsx file below.

    4. Create the Client Pages​

    info

    We are using Tailwind CSS to style the pages. Read more about how to add it here.

    Let's create a auth.tsx file in the src/pages folder and add the following to it:

    src/pages/auth.jsx
    import { LoginForm, SignupForm } from 'wasp/client/auth'
    import { Link } from 'react-router-dom'

    export function Login() {
      return (
        <Layout>
          <LoginForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            Don't have an account yet? <Link to="/signup">go to signup</Link>.
          </span>
        </Layout>
      );
    }

    export function Signup() {
      return (
        <Layout>
          <SignupForm />
          <br />
          <span className="text-sm font-medium text-gray-900">
            I already have an account (<Link to="/login">go to login</Link>).
          </span>
        </Layout>
      );
    }

    // A layout component to center the content
    export function Layout({ children }) {
      return (
        <div className="w-full h-full bg-white">
          <div className="min-w-full min-h-[75vh] flex items-center justify-center">
            <div className="w-full h-full max-w-sm p-5 bg-white">
              <div>{children}</div>
            </div>
          </div>
        </div>
      );
    }

    We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

    Conclusion​

    That's it! We have set up username authentication in our app. 🎉

    Running wasp db migrate-dev and then wasp start should give you a working app with username authentication. If you want to put some of the pages behind authentication, read the auth overview docs.

    Using multiple auth identities for a single user

    Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the account merging feature.

    Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.

    Customizing the Auth Flow​

    The login and signup flows are pretty standard: they allow the user to sign up and then log in with their username and password. The signup flow validates the username and password and then creates a new user entity in the database.

    Read more about the default username and password validation rules in the auth overview docs.

    If you require more control in your authentication flow, you can achieve that in the following ways:

    1. Create your UI and use signup and login actions.
    2. Create your custom sign-up action which uses the lower-level API, along with your custom code.

    1. Using the signup and login actions​

    login()​

    An action for logging in the user.

    It takes two arguments:

    • username: string required

      Username of the user logging in.

    • password: string required

      Password of the user logging in.

    You can use it like this:

    src/pages/auth.jsx
    import { login } from 'wasp/client/auth'

    import { useState } from 'react'
    import { useHistory, Link } from 'react-router-dom'

    export function LoginPage() {
      const [username, setUsername] = useState('')
      const [password, setPassword] = useState('')
      const [error, setError] = useState(null)
      const history = useHistory()

      async function handleSubmit(event) {
        event.preventDefault()
        try {
          await login(username, password)
          history.push('/')
        } catch (error) {
          setError(error)
        }
      }

      return (
        <form onSubmit={handleSubmit}>
          {/* ... */}
        </form>
      );
    }
    note

    When using the exposed login() function, make sure to implement your redirect on success login logic (e.g. redirecting to home).

    signup()​

    An action for signing up the user. This action does not log in the user, you still need to call login().

    It takes one argument:

    • userFields: object required

      It has the following fields:

      • username: string required

      • password: string required

      info

      By default, Wasp will only save the username and password fields. If you want to add extra fields to your signup process, read about defining extra signup fields.

    You can use it like this:

    src/pages/auth.jsx
    import { signup, login } from 'wasp/client/auth'

    import { useState } from 'react'
    import { useHistory } from 'react-router-dom'
    import { Link } from 'react-router-dom'

    export function Signup() {
      const [username, setUsername] = useState('')
      const [password, setPassword] = useState('')
      const [error, setError] = useState(null)
      const history = useHistory()

      async function handleSubmit(event) {
        event.preventDefault()
        try {
          await signup({
            username,
            password,
          })
          await login(username, password)
          history.push("/")
        } catch (error) {
          setError(error)
        }
      }

      return (
        <form onSubmit={handleSubmit}>
          {/* ... */}
        </form>
      );
    }

    2. Creating your custom sign-up action​

    The code of your custom sign-up action can look like this:

    main.wasp
    // ...

    action customSignup {
      fn: import { signup } from "@src/auth/signup.js",
    }
    src/auth/signup.js
    import {
      ensurePasswordIsPresent,
      ensureValidPassword,
      ensureValidUsername,
      createProviderId,
      sanitizeAndSerializeProviderData,
      createUser,
    } from 'wasp/server/auth'

    export const signup = async (args, _context) => {
      ensureValidUsername(args)
      ensurePasswordIsPresent(args)
      ensureValidPassword(args)

      try {
        const providerId = createProviderId('username', args.username)
        const providerData = await sanitizeAndSerializeProviderData({
          hashedPassword: args.password,
        })

        await createUser(
          providerId,
          providerData,
          // Any additional data you want to store on the User entity
          {},
        )
      } catch (e) {
        return {
          success: false,
          message: e.message,
        }
      }

      // Your custom code after sign-up.
      // ...

      return {
        success: true,
        message: 'User created successfully',
      }
    }

    We suggest using the built-in field validators for your authentication flow. You can import them from wasp/server/auth. These are the same validators that Wasp uses internally for the default authentication flow.

    Username​

    • ensureValidUsername(args)

      Checks if the username is valid and throws an error if it's not. Read more about the validation rules here.

    Password​

    • ensurePasswordIsPresent(args)

      Checks if the password is present and throws an error if it's not.

    • ensureValidPassword(args)

      Checks if the password is valid and throws an error if it's not. Read more about the validation rules here.

    Using Auth​

    To read more about how to set up the logout button and how to get access to the logged-in user in our client and server code, read the auth overview docs.

    getUsername​

    If you are looking to access the user's username in your code, you can do that by accessing the info about the user that is stored in the user.auth.identities array.

    To make things a bit easier for you, Wasp offers the getUsername helper.

    The getUsername helper returns the user's username or null if the user doesn't have a username auth identity.

    src/MainPage.jsx
    import { getUsername } from 'wasp/auth'

    const MainPage = ({ user }) => {
      const username = getUsername(user)
      // ...
    }
    src/tasks.js
    import { getUsername } from 'wasp/auth'

    export const createTask = async (args, context) => {
      const username = getUsername(context.user)
      // ...
    }

    API Reference​

    userEntity fields​

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login"
      }
    }

    entity User {=psl
        id                        Int           @id @default(autoincrement())
    psl=}

    The user entity needs to have the following fields:

    • id required

      It can be of any type, but it needs to be marked with @id

    You can add any other fields you want to the user entity. Make sure to also define them in the userSignupFields field if they need to be set during the sign-up process.

    Fields in the usernameAndPassword dict​

    main.wasp
    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {
            userSignupFields: import { userSignupFields } from "@src/auth/email.js",
          },
        },
        onAuthFailedRedirectTo: "/login"
      }
    }
    // ...

    userSignupFields: ExtImport​

    userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

    src/auth.js
    import { defineUserSignupFields } from 'wasp/server/auth'

    export const userSignupFields = defineUserSignupFields({
      address: (data) => {
        if (!data.address) {
          throw new Error('Address is required')
        }
        return data.address
      }
      phone: (data) => data.phone,
    })
    Read more about the `userSignupFields` function [here](./overview#1-defining-extra-fields).
    + + \ No newline at end of file diff --git a/docs/contact.html b/docs/contact.html index c39825e88c..05230a4b23 100644 --- a/docs/contact.html +++ b/docs/contact.html @@ -19,13 +19,13 @@ - - + + -
    -
    - - +
    +
    + + \ No newline at end of file diff --git a/docs/contributing.html b/docs/contributing.html index c7e5eec587..9593743afe 100644 --- a/docs/contributing.html +++ b/docs/contributing.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Contributing

    Any way you want to contribute is a good way, and we'd be happy to meet you! A single entry point for all contributors is the CONTRIBUTING.md file in our Github repo. All the requirements and instructions are there, so please check CONTRIBUTING.md for more details.

    Some side notes to make your journey easier:

    1. Join us on Discord 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. That means you'll need to be somewhat familiar with this language if you'd like to contribute to the compiler itself. But Haskell is just a part of Wasp, and you can contribute to lot of parts that require web dev skills, either by coding or by suggesting how to improve Wasp and its design as a web framework. 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 and make an issue/PR!

    Happy hacking!

    - - +
    +
    Version: 0.13.0

    Contributing

    Any way you want to contribute is a good way, and we'd be happy to meet you! A single entry point for all contributors is the CONTRIBUTING.md file in our Github repo. All the requirements and instructions are there, so please check CONTRIBUTING.md for more details.

    Some side notes to make your journey easier:

    1. Join us on Discord 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. That means you'll need to be somewhat familiar with this language if you'd like to contribute to the compiler itself. But Haskell is just a part of Wasp, and you can contribute to lot of parts that require web dev skills, either by coding or by suggesting how to improve Wasp and its design as a web framework. 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 and make an issue/PR!

    Happy hacking!

    + + \ No newline at end of file diff --git a/docs/data-model/backends.html b/docs/data-model/backends.html index 8afacca224..dbac028fd3 100644 --- a/docs/data-model/backends.html +++ b/docs/data-model/backends.html @@ -19,12 +19,12 @@ - - + + -
    -
    Version: 0.13.0

    Databases

    Entities, Operations and Automatic CRUD together make a high-level interface for working with your app's data. Still, all that data has to live somewhere, so let's see how Wasp deals with databases.

    Supported Database Backends​

    Wasp supports multiple database backends. We'll list and explain each one.

    SQLite​

    The default database Wasp uses is SQLite.

    SQLite is a great way for getting started with a new project because it doesn't require any configuration, but Wasp can only use it in development. Once you want to deploy your Wasp app to production, you'll need to switch to PostgreSQL and stick with it.

    Fortunately, migrating from SQLite to PostgreSQL is pretty simple, and we have a guide to help you.

    PostgreSQL​

    PostgreSQL is the most advanced open-source database and one of the most popular databases overall. +

    +
    Version: 0.13.0

    Databases

    Entities, Operations and Automatic CRUD together make a high-level interface for working with your app's data. Still, all that data has to live somewhere, so let's see how Wasp deals with databases.

    Supported Database Backends​

    Wasp supports multiple database backends. We'll list and explain each one.

    SQLite​

    The default database Wasp uses is SQLite.

    SQLite is a great way for getting started with a new project because it doesn't require any configuration, but Wasp can only use it in development. Once you want to deploy your Wasp app to production, you'll need to switch to PostgreSQL and stick with it.

    Fortunately, migrating from SQLite to PostgreSQL is pretty simple, and we have a guide to help you.

    PostgreSQL​

    PostgreSQL is the most advanced open-source database and one of the most popular databases overall. It's been in active development for 20+ years. Therefore, if you're looking for a battle-tested database, look no further.

    To use Wasp with PostgreSQL, you'll have to ensure a database instance is running during development. Wasp needs access to your database for commands such as wasp start or wasp db migrate-dev and expects to find a connection string in the DATABASE_URL environment variable.

    We cover all supported ways of connecting to a database in the next section.

    Migrating from SQLite to PostgreSQL​

    To run your Wasp app in production, you'll need to switch from SQLite to PostgreSQL.

    1. Set the app.db.system field to PostgreSQL.
    main.wasp
    app MyApp {
      title: "My app",
      // ...
      db: {
        system: PostgreSQL,
        // ...
      }
    }
    1. Delete all the old migrations, since they are SQLite migrations and can't be used with PostgreSQL, as well as the SQLite database by running wasp clean:
    rm -r migrations/
    wasp clean
    1. Ensure your new database is running (check the section on connecting to a database to see how). Leave it running, since we need it for the next step.
    2. In a different terminal, run wasp db migrate-dev to apply the changes and create a new initial migration.
    3. That is it, you are all done!

    Connecting to a Database​

    Assuming you're not using SQLite, Wasp offers two ways of connecting your app to a database instance:

    1. A ready-made dev database that requires minimal setup and is great for quick prototyping.
    2. A "real" database Wasp can connect to and use in production.

    Using the Dev Database Provided by Wasp​

    The command wasp start db will start a default PostgreSQL dev database for you.

    Your Wasp app will automatically connect to it, just keep wasp start db running in the background. Also, make sure that:

    Connecting to an existing database​

    If you want to spin up your own dev database (or connect to an external one), you can tell Wasp about it using the DATABASE_URL environment variable. Wasp will use the value of DATABASE_URL as a connection string.

    The easiest way to set the necessary DATABASE_URL environment variable is by adding it to the .env.server file in the root dir of your Wasp project (if that file doesn't yet exist, create it).

    Alternatively, you can set it inline when running wasp (this applies to all environment variables):

    DATABASE_URL=<my-db-url> wasp ...

    This trick is useful for running a certain wasp command on a specific database. @@ -36,7 +36,7 @@ Whenever you modify the db.system field, make sure to run wasp db migrate-dev to apply the changes.

  • seeds: [ExtImport]

    Defines the seed functions you can use with the wasp db seed command to seed your database with initial data. Read the Seeding section for more details.

  • prisma: PrismaOptions

    Additional configuration for Prisma.

    main.wasp
    app MyApp {
      // ...
      db: {
        // ...
        prisma: {
          clientPreviewFeatures: ["postgresqlExtensions"],
          dbExtensions: [
            { name: "hstore", schema: "myHstoreSchema" },
            { name: "pg_trgm" },
            { name: "postgis", version: "2.1" },
          ]
        }
      }
    }

    It's a dictionary with the following fields:

    • clientPreviewFeatures : [string]

      Allows you to define Prisma client preview features, like for example, "postgresqlExtensions".

    • dbExtensions: DbExtension[]

      It allows you to define PostgreSQL extensions that should be enabled for your database. Read more about PostgreSQL extensions in Prisma.

      For each extension you define a dict with the following fields:

      • name: string required

        The name of the extension you would normally put in the Prisma file.

        schema.prisma
        extensions = [hstore(schema: "myHstoreSchema"), pg_trgm, postgis(version: "2.1")]
        //              👆 Extension name

      • map: string

        It sets the map argument of the extension. Explanation for the field from the Prisma docs:

        This is the database name of the extension. If this argument is not specified, the name of the extension in the Prisma schema must match the database name.

      • schema: string

        It sets the schema argument of the extension. Explanation for the field from the Prisma docs:

        This is the name of the schema in which to activate the extension's objects. If this argument is not specified, the current default object creation schema is used.

      • version: string

        It sets the version argument of the extension. Explanation for the field from the Prisma docs:

        This is the version of the extension to activate. If this argument is not specified, the value given in the extension's control file is used.

    • CLI Commands for Seeding the Database​

    Use one of the following commands to run the seed functions:

    • wasp db seed

      If you've only defined a single seed function, this command runs it. If you've defined multiple seed functions, it asks you to choose one interactively.

    • wasp db seed <seed-name>

      This command runs the seed function with the specified name. The name is the identifier used in its import expression in the app.db.seeds list. For example, to run the seed function devSeedSimple which was defined like this:

      main.wasp
      app MyApp {
        // ...
        db: {
          // ...
          seeds: [
            // ...
            import { devSeedSimple } from "@src/dbSeeds.js",
          ]
        }
      }

      Use the following command:

      wasp db seed devSeedSimple
    - - + + \ No newline at end of file diff --git a/docs/data-model/crud.html b/docs/data-model/crud.html index 3ac6ace628..b1111c39ee 100644 --- a/docs/data-model/crud.html +++ b/docs/data-model/crud.html @@ -19,15 +19,15 @@ - - + + -
    -
    Version: 0.13.0

    Automatic CRUD

    If you have a lot of experience writing full-stack apps, you probably ended up doing some of the same things many times: listing data, adding data, editing it, and deleting it.

    Wasp makes handling these boring bits easy by offering a higher-level concept called Automatic CRUD.

    With a single declaration, you can tell Wasp to automatically generate server-side logic (i.e., Queries and Actions) for creating, reading, updating and deleting Entities. As you update definitions for your Entities, Wasp automatically regenerates the backend logic.

    Early preview

    This feature is currently in early preview and we are actively working on it. Read more about our plans for CRUD operations.

    Overview​

    Imagine we have a Task entity and we want to enable CRUD operations for it.

    main.wasp
    entity Task {=psl
      id          Int @id @default(autoincrement())
      description String
      isDone      Boolean
    psl=}

    We can then define a new crud called Tasks.

    We specify to use the Task entity and we enable the getAll, get, create and update operations (let's say we don't need the delete operation).

    main.wasp
    crud Tasks {
      entity: Task,
      operations: {
        getAll: {
          isPublic: true, // by default only logged in users can perform operations
        },
        get: {},
        create: {
          overrideFn: import { createTask } from "@src/tasks.js",
        },
        update: {},
      },
    }
    1. It uses default implementation for getAll, get, and update,
    2. ... while specifying a custom implementation for create.
    3. getAll will be public (no auth needed), while the rest of the operations will be private.

    Here's what it looks like when visualized:

    Automatic CRUD with Wasp
    Visualization of the Tasks crud declaration

    We can now use the CRUD queries and actions we just specified in our client code.

    Keep reading for an example of Automatic CRUD in action, or skip ahead for the API Reference

    Example: A Simple TODO App​

    Let's create a full-app example that uses automatic CRUD. We'll stick to using the Task entity from the previous example, but we'll add a User entity and enable username and password based auth.

    Automatic CRUD with Wasp
    We are building a simple tasks app with username based auth

    Creating the App​

    We can start by running wasp new tasksCrudApp and then adding the following to the main.wasp file:

    main.wasp
    app tasksCrudApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "Tasks Crud App",

      // We enabled auth and set the auth method to username and password
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login",
      },
    }

    entity User {=psl
      id       Int @id @default(autoincrement())
      tasks    Task[]
    psl=}

    // We defined a Task entity on which we'll enable CRUD later on
    entity Task {=psl
      id          Int @id @default(autoincrement())
      description String
      isDone      Boolean
      userId      Int
      user        User @relation(fields: [userId], references: [id])
    psl=}

    // Tasks app routes
    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      component: import { MainPage } from "@src/MainPage.jsx",
      authRequired: true,
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage.jsx",
    }

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage.jsx",
    }

    We can then run wasp db migrate-dev to create the database and run the migrations.

    Adding CRUD to the Task Entity ✨​

    Let's add the following crud declaration to our main.wasp file:

    main.wasp
    // ...

    crud Tasks {
      entity: Task,
      operations: {
        getAll: {},
        create: {
          overrideFn: import { createTask } from "@src/tasks.js",
        },
      },
    }

    You'll notice that we enabled only getAll and create operations. This means that only these operations will be available.

    We also overrode the create operation with a custom implementation. This means that the create operation will not be generated, but instead, the createTask function from @src/tasks.js will be used.

    Our Custom create Operation​

    Here's the src/tasks.ts file:

    src/tasks.js
    import { HttpError } from 'wasp/server'

    export const createTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401, 'User not authenticated.')
      }

      const { description, isDone } = args
      const { Task } = context.entities

      return await Task.create({
        data: {
          description,
          isDone,
          // Connect the task to the user that is creating it
          user: {
            connect: {
              id: context.user.id,
            },
          },
        },
      })
    }

    We made a custom create operation because we want to make sure that the task is connected to the user that is creating it. +

    +
    Version: 0.13.0

    Automatic CRUD

    If you have a lot of experience writing full-stack apps, you probably ended up doing some of the same things many times: listing data, adding data, editing it, and deleting it.

    Wasp makes handling these boring bits easy by offering a higher-level concept called Automatic CRUD.

    With a single declaration, you can tell Wasp to automatically generate server-side logic (i.e., Queries and Actions) for creating, reading, updating and deleting Entities. As you update definitions for your Entities, Wasp automatically regenerates the backend logic.

    Early preview

    This feature is currently in early preview and we are actively working on it. Read more about our plans for CRUD operations.

    Overview​

    Imagine we have a Task entity and we want to enable CRUD operations for it.

    main.wasp
    entity Task {=psl
      id          Int @id @default(autoincrement())
      description String
      isDone      Boolean
    psl=}

    We can then define a new crud called Tasks.

    We specify to use the Task entity and we enable the getAll, get, create and update operations (let's say we don't need the delete operation).

    main.wasp
    crud Tasks {
      entity: Task,
      operations: {
        getAll: {
          isPublic: true, // by default only logged in users can perform operations
        },
        get: {},
        create: {
          overrideFn: import { createTask } from "@src/tasks.js",
        },
        update: {},
      },
    }
    1. It uses default implementation for getAll, get, and update,
    2. ... while specifying a custom implementation for create.
    3. getAll will be public (no auth needed), while the rest of the operations will be private.

    Here's what it looks like when visualized:

    Automatic CRUD with Wasp
    Visualization of the Tasks crud declaration

    We can now use the CRUD queries and actions we just specified in our client code.

    Keep reading for an example of Automatic CRUD in action, or skip ahead for the API Reference

    Example: A Simple TODO App​

    Let's create a full-app example that uses automatic CRUD. We'll stick to using the Task entity from the previous example, but we'll add a User entity and enable username and password based auth.

    Automatic CRUD with Wasp
    We are building a simple tasks app with username based auth

    Creating the App​

    We can start by running wasp new tasksCrudApp and then adding the following to the main.wasp file:

    main.wasp
    app tasksCrudApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "Tasks Crud App",

      // We enabled auth and set the auth method to username and password
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login",
      },
    }

    entity User {=psl
      id       Int @id @default(autoincrement())
      tasks    Task[]
    psl=}

    // We defined a Task entity on which we'll enable CRUD later on
    entity Task {=psl
      id          Int @id @default(autoincrement())
      description String
      isDone      Boolean
      userId      Int
      user        User @relation(fields: [userId], references: [id])
    psl=}

    // Tasks app routes
    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      component: import { MainPage } from "@src/MainPage.jsx",
      authRequired: true,
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage.jsx",
    }

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage.jsx",
    }

    We can then run wasp db migrate-dev to create the database and run the migrations.

    Adding CRUD to the Task Entity ✨​

    Let's add the following crud declaration to our main.wasp file:

    main.wasp
    // ...

    crud Tasks {
      entity: Task,
      operations: {
        getAll: {},
        create: {
          overrideFn: import { createTask } from "@src/tasks.js",
        },
      },
    }

    You'll notice that we enabled only getAll and create operations. This means that only these operations will be available.

    We also overrode the create operation with a custom implementation. This means that the create operation will not be generated, but instead, the createTask function from @src/tasks.js will be used.

    Our Custom create Operation​

    Here's the src/tasks.ts file:

    src/tasks.js
    import { HttpError } from 'wasp/server'

    export const createTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401, 'User not authenticated.')
      }

      const { description, isDone } = args
      const { Task } = context.entities

      return await Task.create({
        data: {
          description,
          isDone,
          // Connect the task to the user that is creating it
          user: {
            connect: {
              id: context.user.id,
            },
          },
        },
      })
    }

    We made a custom create operation because we want to make sure that the task is connected to the user that is creating it. Automatic CRUD doesn't support this by default (yet!). Read more about the default implementations here.

    Using the Generated CRUD Operations on the Client​

    And let's use the generated operations in our client code:

    src/MainPage.jsx
    import { Tasks } from 'wasp/client/crud'
    import { useState } from 'react'

    export const MainPage = () => {
      const { data: tasks, isLoading, error } = Tasks.getAll.useQuery()
      const createTask = Tasks.create.useAction()
      const [taskDescription, setTaskDescription] = useState('')

      function handleCreateTask() {
        createTask({ description: taskDescription, isDone: false })
        setTaskDescription('')
      }

      if (isLoading) return <div>Loading...</div>
      if (error) return <div>Error: {error.message}</div>
      return (
        <div
          style={{
            fontSize: '1.5rem',
            display: 'grid',
            placeContent: 'center',
            height: '100vh',
          }}
        >
          <div>
            <input
              value={taskDescription}
              onChange={(e) => setTaskDescription(e.target.value)}
            />
            <button onClick={handleCreateTask}>Create task</button>
          </div>
          <ul>
            {tasks.map((task) => (
              <li key={task.id}>{task.description}</li>
            ))}
          </ul>
        </div>
      )
    }

    And here are the login and signup pages, where we are using Wasp's Auth UI components:

    src/LoginPage.jsx
    import { LoginForm } from 'wasp/client/auth'
    import { Link } from 'react-router-dom'

    export function LoginPage() {
      return (
        <div
          style={{
            display: 'grid',
            placeContent: 'center',
          }}
        >
          <LoginForm />
          <div>
            <Link to="/signup">Create an account</Link>
          </div>
        </div>
      )
    }
    src/SignupPage.jsx
    import { SignupForm } from 'wasp/client/auth'

    export function SignupPage() {
      return (
        <div
          style={{
            display: 'grid',
            placeContent: 'center',
          }}
        >
          <SignupForm />
        </div>
      )
    }

    That's it. You can now run wasp start and see the app in action. ⚡️

    You should see a login page and a signup page. After you log in, you should see a page with a list of tasks and a form to create new tasks.

    Future of CRUD Operations in Wasp​

    CRUD operations currently have a limited set of knowledge about the business logic they are implementing.

    • For example, they don't know that a task should be connected to the user that is creating it. This is why we had to override the create operation in the example above.
    • Another thing: they are not aware of the authorization rules. For example, they don't know that a user should not be able to create a task for another user. In the future, we will be adding role-based authorization to Wasp, and we plan to make CRUD operations aware of the authorization rules.
    • Another issue is input validation and sanitization. For example, we might want to make sure that the task description is not empty.

    CRUD operations are a mechanism for getting a backend up and running quickly, but it depends on the information it can get from the Wasp app. The more information that it can pick up from your app, the more powerful it will be out of the box.

    We plan on supporting CRUD operations and growing them to become the easiest way to create your backend. Follow along on this GitHub issue to see how we are doing.

    API Reference​

    CRUD declaration work on top of existing entity declaration. We'll fully explore the API using two examples:

    1. A basic CRUD declaration that relies on default options.
    2. A more involved CRUD declaration that uses extra options and overrides.

    Declaring a CRUD With Default Options​

    If we create CRUD operations for an entity named Task, like this:

    main.wasp
    crud Tasks { // crud name here is "Tasks"
      entity: Task,
      operations: {
        get: {},
        getAll: {},
        create: {},
        update: {},
        delete: {},
      },
    }

    Wasp will give you the following default implementations:

    get - returns one entity based on the id field

    // ...
    // Wasp uses the field marked with `@id` in Prisma schema as the id field.
    return Task.findUnique({ where: { id: args.id } })

    getAll - returns all entities

    // ...

    // If the operation is not public, Wasp checks if an authenticated user
    // is making the request.

    return Task.findMany()

    create - creates a new entity

    // ...
    return Task.create({ data: args.data })

    update - updates an existing entity

    // ...
    // Wasp uses the field marked with `@id` in Prisma schema as the id field.
    return Task.update({ where: { id: args.id }, data: args.data })

    delete - deletes an existing entity

    // ...
    // Wasp uses the field marked with `@id` in Prisma schema as the id field.
    return Task.delete({ where: { id: args.id } })
    Current Limitations

    In the default create and update implementations, we are saving all of the data that the client sends to the server. This is not always desirable, i.e. in the case when the client should not be able to modify all of the data in the entity.

    In the future, we are planning to add validation of action input, where only the data that the user is allowed to change will be saved.

    For now, the solution is to provide an override function. You can override the default implementation by using the overrideFn option and implementing the validation logic yourself.

    Declaring a CRUD With All Available Options​

    Here's an example of a more complex CRUD declaration:

    main.wasp
    crud Tasks { // crud name here is "Tasks"
      entity: Task,
      operations: {
        getAll: {
          isPublic: true, // optional, defaults to false
        },
        get: {},
        create: {
          overrideFn: import { createTask } from "@src/tasks.js", // optional
        },
        update: {},
      },
    }

    The CRUD declaration features the following fields:

    • entity: Entity required

      The entity to which the CRUD operations will be applied.

    • operations: { [operationName]: CrudOperationOptions } required

      The operations to be generated. The key is the name of the operation, and the value is the operation configuration.

      • The possible values for operationName are:
        • getAll
        • get
        • create
        • update
        • delete
      • CrudOperationOptions can have the following fields:
        • isPublic: bool - Whether the operation is public or not. If it is public, no auth is required to access it. If it is not public, it will be available only to authenticated users. Defaults to false.
        • overrideFn: ExtImport - The import statement of the optional override implementation in Node.js.

    Defining the overrides​

    Like with actions and queries, you can define the implementation in a Javascript/Typescript file. The overrides are functions that take the following arguments:

    • args

      The arguments of the operation i.e. the data sent from the client.

    • context

      Context contains the user making the request and the entities object with the entity that's being operated on.

    For a usage example, check the example guide.

    Using the CRUD operations in client code​

    On the client, you import the CRUD operations from wasp/client/crud by import the {crud name} object. For example, if you have a CRUD called Tasks, you would import the operations like this:

    SomePage.jsx
    import { Tasks } from 'wasp/client/crud'

    You can then access the operations like this:

    SomePage.jsx
    const { data } = Tasks.getAll.useQuery()
    const { data } = Tasks.get.useQuery({ id: 1 })
    const createAction = Tasks.create.useAction()
    const updateAction = Tasks.update.useAction()
    const deleteAction = Tasks.delete.useAction()

    All CRUD operations are implemented with Queries and Actions under the hood, which means they come with all the features you'd expect (e.g., automatic SuperJSON serialization, full-stack type safety when using TypeScript)

    Join our community on Discord, where we chat about full-stack web stuff. Join us to see what we are up to, share your opinions or get help with CRUD operations.

    - - + + \ No newline at end of file diff --git a/docs/data-model/entities.html b/docs/data-model/entities.html index bb261dae83..9690cda712 100644 --- a/docs/data-model/entities.html +++ b/docs/data-model/entities.html @@ -19,15 +19,15 @@ - - + + -
    -
    Version: 0.13.0

    Entities

    Entities are the foundation of your app's data model. In short, an Entity defines a model in your database.

    Wasp uses the excellent Prisma ORM to implement all database functionality and occasionally enhances it with a thin abstraction layer. +

    +
    Version: 0.13.0

    Entities

    Entities are the foundation of your app's data model. In short, an Entity defines a model in your database.

    Wasp uses the excellent Prisma ORM to implement all database functionality and occasionally enhances it with a thin abstraction layer. Wasp Entities directly correspond to Prisma's data model. Still, you don't need to be familiar with Prisma to effectively use Wasp, as it comes with a simple API wrapper for working with Prisma's core features.

    The only requirement for defining Wasp Entities is familiarity with the Prisma Schema Language (PSL), a simple definition language explicitly created for defining models in Prisma. The language is declarative and very intuitive. We'll also go through an example later in the text, so there's no need to go and thoroughly learn it right away. Still, if you're curious, look no further than Prisma's official documentation:

    Defining an Entity​

    As mentioned, an entity declaration represents a database model.

    Each Entity declaration corresponds 1-to-1 to Prisma's data model. Here's how you could define an Entity that represents a Task:

    entity Task {=psl
        id          Int     @id @default(autoincrement())
        description String
        isDone      Boolean @default(false)
    psl=}

    Let's go through this declaration in detail:

    • entity Task - This tells Wasp that we wish to define an Entity (i.e., database model) called Task. Wasp automatically creates a table called tasks.
    • {=psl ... psl=} - Wasp treats everything that comes between the two psl tags as PSL (Prisma Schema Language).

    The above PSL definition tells Wasp to create a table for storing Tasks where each task has three fields (i.e., the tasks table has three columns):

    • id - An integer value serving as a primary key. The database automatically generates it by incrementing the previously generated id.
    • description - A string value for storing the task's description.
    • isDone - A boolean value indicating the task's completion status. If you don't set it when creating a new task, the database sets it to false by default.

    Working with Entities​

    Let's see how you can define and work with Wasp Entities:

    1. Create/update some Entities in your .wasp file.
    2. Run wasp db migrate-dev. This command syncs the database model with the Entity definitions in your .wasp file. It does this by creating migration scripts.
    3. Migration scripts are automatically placed in the migrations/ folder. Make sure to commit this folder into version control.
    4. Use Wasp's JavasScript API to work with the database when implementing Operations (we'll cover this in detail when we talk about operations).

    Using Entities in Operations​

    Most of the time, you will be working with Entities within the context of Operations (Queries & Actions). We'll see how that's done on the next page.

    Using Entities directly​

    If you need more control, you can directly interact with Entities by importing and using the Prisma Client. We recommend sticking with conventional Wasp-provided mechanisms, only resorting to directly using the Prisma client only if you need a feature Wasp doesn't provide.

    You can only use the Prisma Client in your Wasp server code. You can import it like this:

    import { prisma } from 'wasp/server'

    prisma.task.create({
        description: "Read the Entities doc",
        isDone: true // almost :)
    })

    Next steps​

    Now that we've seen how to define Entities that represent Wasp's core data model, we'll see how to make the most of them in other parts of Wasp. Keep reading to learn all about Wasp Operations!

    - - + + \ No newline at end of file diff --git a/docs/data-model/operations/actions.html b/docs/data-model/operations/actions.html index 01f0cb2128..9fb294fcc7 100644 --- a/docs/data-model/operations/actions.html +++ b/docs/data-model/operations/actions.html @@ -19,12 +19,12 @@ - - + + -
    -
    Version: 0.13.0

    Actions

    We'll explain what Actions are and how to use them. If you're looking for a detailed API specification, skip ahead to the API Reference.

    Actions are quite similar to Queries, but with a key distinction: Actions are designed to modify and add data, while Queries are solely for reading data. Examples of Actions include adding a comment to a blog post, liking a video, or updating a product's price.

    Actions and Queries work together to keep data caches up-to-date.

    tip

    Actions are almost identical to Queries in terms of their API. +

    +
    Version: 0.13.0

    Actions

    We'll explain what Actions are and how to use them. If you're looking for a detailed API specification, skip ahead to the API Reference.

    Actions are quite similar to Queries, but with a key distinction: Actions are designed to modify and add data, while Queries are solely for reading data. Examples of Actions include adding a comment to a blog post, liking a video, or updating a product's price.

    Actions and Queries work together to keep data caches up-to-date.

    tip

    Actions are almost identical to Queries in terms of their API. Therefore, if you're already familiar with Queries, you might find reading the entire guide repetitive.

    We instead recommend skipping ahead and only reading the differences between Queries and Actions, and consulting the API Reference as needed.

    Working with Actions​

    Actions are declared in Wasp and implemented in NodeJS. Wasp runs Actions within the server's context, but it also generates code that allows you to call them from anywhere in your code (either client or server) using the same interface.

    This means you don't have to worry about building an HTTP API for the Action, managing server-side request handling, or even dealing with client-side response handling and caching. Instead, just focus on developing the business logic inside your Action, and let Wasp handle the rest!

    To create an Action, you need to:

    1. Declare the Action in Wasp using the action declaration.
    2. Implement the Action's NodeJS functionality.

    Once these two steps are completed, you can use the Action from anywhere in your code.

    Declaring Actions​

    To create an Action in Wasp, we begin with an action declaration. Let's declare two Actions - one for creating a task, and another for marking tasks as done:

    main.wasp
    // ...

    action createTask {
      fn: import { createTask } from "@src/actions.js"
    }

    action markTaskAsDone {
      fn: import { markTaskAsDone } from "@src/actions.js"
    }

    If you want to know about all supported options for the action declaration, take a look at the API Reference.

    The names of Wasp Actions and their implementations don't necessarily have to match. However, to avoid confusion, we'll keep them the same.

    tip

    Wasp uses superjson under the hood. This means you're not limited to only sending and receiving JSON payloads.

    You can send and receive any superjson-compatible payload (like Dates, Sets, Lists, circular references, etc.) and let Wasp handle the (de)serialization.

    After declaring a Wasp Action, two important things happen:

    • Wasp generates a server-side NodeJS function that shares its name with the Action.

    • Wasp generates a client-side JavaScript function that shares its name with the Action (e.g., markTaskAsDone). @@ -42,7 +42,7 @@ Since both arguments are positional, you can name the parameters however you want, but we'll stick with args and context:

      1. args (type depends on the Action)

        An object containing the data passed in when calling the Action (e.g., filtering conditions). Check the usage examples to see how to pass this object to the Action.

      2. context (type depends on the Action)

        An additional context object passed into the Action by Wasp. This object contains user session information, as well as information about entities. Check the section about using entities in Actions to see how to use the entities field on the context object, or the auth section to see how to use the user object.

      Example​

      The following Action:

      action createFoo {
          fn: import { createFoo } from "@src/actions.js"
          entities: [Foo]
      }

      Expects to find a named export createfoo from the file src/actions.js

      actions.js
      export const createFoo = (args, context) => {
        // implementation
      }

      The useAction Hook and Optimistic Updates​

      Make sure you understand how Queries and Cache Invalidation work before reading this chapter.

      When using Actions in components, you can enhance them with the help of the useAction hook. This hook comes bundled with Wasp, and is used for decorating Wasp Actions. In other words, the hook returns a function whose API matches the original Action while also doing something extra under the hood (depending on how you configure it).

      The useAction hook accepts two arguments:

      • actionFn required

        The Wasp Action (i.e., the client-side Action function generated by Wasp based on a Action declaration) you wish to enhance.

      • actionOptions

        An object configuring the extra features you want to add to the given Action. While this argument is technically optional, there is no point in using the useAction hook without providing it (it would be the same as using the Action directly). The Action options object supports the following fields:

        • optimisticUpdates

          An array of objects where each object defines an optimistic update to perform on the Query cache. To define an optimistic update, you must specify the following properties:

          • getQuerySpecifier required

          A function returning the Query specifier (i.e., a value used to address the Query you want to update). A Query specifier is an array specifying the query function and arguments. For example, to optimistically update the Query used with useQuery(fetchFilteredTasks, {isDone: true }], your getQuerySpecifier function would have to return the array [fetchFilteredTasks, { isDone: true}]. Wasp will forward the argument you pass into the decorated Action to this function (i.e., you can use the properties of the added/changed item to address the Query).

          • updateQuery required

          The function used to perform the optimistic update. It should return the desired state of the cache. Wasp will call it with the following arguments:

          • item - The argument you pass into the decorated Action.
          • oldData - The currently cached value for the Query identified by the specifier.
      caution

      The updateQuery function must be a pure function. It must return the desired cache value identified by the getQuerySpecifier function and must not perform any side effects.

      Also, make sure you only update the Query caches affected by your Action causing the optimistic update (Wasp cannot yet verify this).

      Finally, your implementation of the updateQuery function should work correctly regardless of the state of oldData (e.g., don't rely on array positioning). If you need to do something else during your optimistic update, you can directly use react-query's lower-level API (read more about it here).

      Here's an example showing how to configure the Action markTaskAsDone that toggles a task's isDone status to perform an optimistic update:

      src/pages/Task.jsx
      import React from 'react'
      import {
        useQuery,
        useAction,
        getTask,
        markTaskAsDone,
      } from 'wasp/client/operations'

      const TaskPage = ({ id }) => {
        const { data: task } = useQuery(getTask, { id })
        const markTaskAsDoneOptimistically = useAction(markTaskAsDone, {
          optimisticUpdates: [
            {
              getQuerySpecifier: ({ id }) => [getTask, { id }],
              updateQuery: (_payload, oldData) => ({ ...oldData, isDone: true }),
            },
          ],
        })

        if (!task) {
          return <h1>"Loading"</h1>
        }

        const { description, isDone } = task
        return (
          <div>
            <p>
              <strong>Description: </strong>
              {description}
            </p>
            <p>
              <strong>Is done: </strong>
              {isDone ? 'Yes' : 'No'}
            </p>
            {isDone || (
              <button onClick={() => markTaskAsDoneOptimistically({ id })}>
                Mark as done.
              </button>
            )}
          </div>
        )
      }

      export default TaskPage

      Advanced usage​

      The useAction hook currently only supports specifying optimistic updates. You can expect more features in future versions of Wasp.

      Wasp's optimistic update API is deliberately small and focuses exclusively on updating Query caches (as that's the most common use case). You might need an API that offers more options or a higher level of control. If that's the case, instead of using Wasp's useAction hook, you can use react-query's useMutation hook and directly work with their low-level API.

      If you decide to use react-query's API directly, you will need access to Query cache key. Wasp internally uses this key but abstracts it from the programmer. Still, you can easily obtain it by accessing the queryCacheKey property on any Query:

      import { getTasks } from 'wasp/client/operations'

      const queryKey = getTasks.queryCacheKey
    - - + + \ No newline at end of file diff --git a/docs/data-model/operations/overview.html b/docs/data-model/operations/overview.html index fc6e90d6c4..da29147d8b 100644 --- a/docs/data-model/operations/overview.html +++ b/docs/data-model/operations/overview.html @@ -19,14 +19,14 @@ - - + + -
    -
    Version: 0.13.0

    Overview

    While Entities enable help you define your app's data model and relationships, Operations are all about working with this data.

    There are two kinds of Operations: Queries and Actions. As their names suggest, +

    +
    - - + + \ No newline at end of file diff --git a/docs/data-model/operations/queries.html b/docs/data-model/operations/queries.html index 4cefa47ce3..7e146396f6 100644 --- a/docs/data-model/operations/queries.html +++ b/docs/data-model/operations/queries.html @@ -19,12 +19,12 @@ - - + + -
    -
    Version: 0.13.0

    Queries

    We'll explain what Queries are and how to use them. If you're looking for a detailed API specification, skip ahead to the API Reference.

    You can use Queries to fetch data from the server. They shouldn't modify the server's state. +

    +
    Version: 0.13.0

    Queries

    We'll explain what Queries are and how to use them. If you're looking for a detailed API specification, skip ahead to the API Reference.

    You can use Queries to fetch data from the server. They shouldn't modify the server's state. Fetching all comments on a blog post, a list of users that liked a video, information about a single product based on its ID... All of these are perfect use cases for a Query.

    tip

    Queries are fairly similar to Actions in terms of their API. Therefore, if you're already familiar with Actions, you might find reading the entire guide repetitive.

    We instead recommend skipping ahead and only reading the differences between Queries and Actions, and consulting the API Reference as needed.

    Working with Queries​

    You declare queries in the .wasp file and implement them using NodeJS. Wasp not only runs these queries within the server's context but also creates code that enables you to call them from any part of your codebase, whether it's on the client or server side.

    This means you don't have to build an HTTP API for your query, manage server-side request handling, or even deal with client-side response handling and caching. Instead, just concentrate on implementing the business logic inside your query, and let Wasp handle the rest!

    To create a Query, you must:

    1. Declare the Query in Wasp using the query declaration.
    2. Define the Query's NodeJS implementation.

    After completing these two steps, you'll be able to use the Query from any point in your code.

    Declaring Queries​

    To create a Query in Wasp, we begin with a query declaration.

    Let's declare two Queries - one to fetch all tasks, and another to fetch tasks based on a filter, such as whether a task is done:

    main.wasp
    // ...

    query getAllTasks {
      fn: import { getAllTasks } from "@src/queries.js"
    }

    query getFilteredTasks {
      fn: import { getFilteredTasks } from "@src/queries.js"
    }

    If you want to know about all supported options for the query declaration, take a look at the API Reference.

    The names of Wasp Queries and their implementations don't need to match, but we'll keep them the same to avoid confusion.

    info

    You might have noticed that we told Wasp to import Query implementations that don't yet exist. Don't worry about that for now. We'll write the implementations imported from queries.ts in the next section.

    It's a good idea to start with the high-level concept (i.e., the Query declaration in the Wasp file) and only then deal with the implementation details (i.e., the Query's implementation in JavaScript).

    After declaring a Wasp Query, two important things happen:

    • Wasp generates a server-side NodeJS function that shares its name with the Query.

    • Wasp generates a client-side JavaScript function that shares its name with the Query (e.g., getFilteredTasks). @@ -46,7 +46,7 @@ behavior for this particular Query. If you want to change the global defaults, you can do so in the client setup function.

    For an example of usage, check this section.

    - - + + \ No newline at end of file diff --git a/docs/editor-setup.html b/docs/editor-setup.html index 7f018f67e5..375c4644e4 100644 --- a/docs/editor-setup.html +++ b/docs/editor-setup.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Editor Setup

    note

    This page assumes you have already installed Wasp. If you do not have Wasp installed yet, check out the Quick Start guide.

    Wasp comes with the Wasp language server, which gives supported editors powerful support and integration with the language.

    VSCode​

    Currently, Wasp only supports integration with VSCode. Install the Wasp language extension to get syntax highlighting and integration with the Wasp language server.

    The extension enables:

    • syntax highlighting for .wasp files
    • scaffolding of new project files
    • code completion
    • diagnostics (errors and warnings)
    • go to definition

    and more!

    - - +
    +
    Version: 0.13.0

    Editor Setup

    note

    This page assumes you have already installed Wasp. If you do not have Wasp installed yet, check out the Quick Start guide.

    Wasp comes with the Wasp language server, which gives supported editors powerful support and integration with the language.

    VSCode​

    Currently, Wasp only supports integration with VSCode. Install the Wasp language extension to get syntax highlighting and integration with the Wasp language server.

    The extension enables:

    • syntax highlighting for .wasp files
    • scaffolding of new project files
    • code completion
    • diagnostics (errors and warnings)
    • go to definition

    and more!

    + + \ No newline at end of file diff --git a/docs/general/cli.html b/docs/general/cli.html index 940d5c13b4..87222006e6 100644 --- a/docs/general/cli.html +++ b/docs/general/cli.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    CLI Reference

    This guide provides an overview of the Wasp CLI commands, arguments, and options.

    Overview​

    Once installed, you can use the wasp command from your command line.

    If you run the wasp command without any arguments, it will show you a list of available commands and their descriptions:

    USAGE
      wasp <command> [command-args]

    COMMANDS
      GENERAL
        new [<name>] [args]   Creates a new Wasp project. Run it without arguments for interactive mode.
          OPTIONS:
            -t|--template <template-name>
               Check out the templates list here: https://github.com/wasp-lang/starters

        new:ai <app-name> <app-description> [<config-json>]
          Uses AI to create a new Wasp project just based on the app name and the description.
          You can do the same thing with `wasp new` interactively.
          Run `wasp new:ai` for more info.

        version               Prints current version of CLI.
        waspls                Run Wasp Language Server. Add --help to get more info.
        completion            Prints help on bash completion.
        uninstall             Removes Wasp from your system.
      IN PROJECT
        start                 Runs Wasp app in development mode, watching for file changes.
        start db              Starts managed development database for you.
        db <db-cmd> [args]    Executes a database command. Run 'wasp db' for more info.
        clean                 Deletes all generated code, all cached artifacts, and the node_modules dir.
                              Wasp equivalent of 'have you tried closing and opening it again?'.
        build                 Generates full web app code, ready for deployment. Use when deploying or ejecting.
        deploy                Deploys your Wasp app to cloud hosting providers.
        telemetry             Prints telemetry status.
        deps                  Prints the dependencies that Wasp uses in your project.
        dockerfile            Prints the contents of the Wasp generated Dockerfile.
        info                  Prints basic information about the current Wasp project.
        test                  Executes tests in your project.
        studio                (experimental) GUI for inspecting your Wasp app.

    EXAMPLES
      wasp new MyApp
      wasp start
      wasp db migrate-dev

    Docs: https://wasp-lang.dev/docs
    Discord (chat): https://discord.gg/rzdnErX
    Newsletter: https://wasp-lang.dev/#signup

    Commands​

    Creating a New Project​

    • Use wasp new to start the interactive mode for setting up a new Wasp project.

      This will prompt you to input the project name and to select a template. The chosen template will then be used to generate the project directory with the specified name.

      $ wasp new
      Enter the project name (e.g. my-project) ▸ MyFirstProject
      Choose a starter template
      [1] basic (default)
          Simple starter template with a single page.
      [2] todo-ts
          Simple but well-rounded Wasp app implemented with Typescript & full-stack type safety.
      [3] saas
          Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check out https://opensaas.sh/ for more details.
      [4] embeddings
          Comes with code for generating vector embeddings and performing vector similarity search.
      [5] ai-generated
          🤖 Describe an app in a couple of sentences and have Wasp AI generate initial code for you. (experimental)
      ▸ 1

      🐝 --- Creating your project from the "basic" template... -------------------------

      Created new Wasp app in ./MyFirstProject directory!

      To run your new app, do:
          cd MyFirstProject
          wasp db start

    • To skip the interactive mode and create a new Wasp project with the default template, use wasp new <project-name>.

      $ wasp new MyFirstProject
      🐝 --- Creating your project from the "basic" template... -------------------------

      Created new Wasp app in ./MyFirstProject directory!

      To run your new app, do:
         cd MyFirstProject
         wasp db start

    Project Commands​

    • wasp start launches the Wasp app in development mode. It automatically opens a browser tab with your application running and watches for any changes to .wasp or files in src/ to automatically reflect in the browser. It also shows messages from the web app, the server and the database on stdout/stderr.

    • wasp start db starts the database for you. This can be very handy since you don't need to spin up your own database or provide its connection URL to the Wasp app.

    • wasp clean removes all generated code and other cached artifacts. If using SQlite, it also deletes the SQlite database. Think of this as the Wasp version of the classic "turn it off and on again" solution.

      $ wasp clean

      🐝 --- Deleting the .wasp/ directory... -------------------------------------------

      ✅ --- Deleted the .wasp/ directory. ----------------------------------------------

      🐝 --- Deleting the node_modules/ directory... ------------------------------------

      ✅ --- Deleted the node_modules/ directory. ---------------------------------------

    • wasp build generates the complete web app code, which is ready for deployment. Use this command when you're deploying or ejecting. The generated code is stored in the .wasp/build folder.

    • wasp deploy makes it easy to get your app hosted on the web.

      Currently, Wasp offers support for Fly.io. If you prefer a different hosting provider, feel free to let us know on Discord or submit a PR by updating this TypeScript app.

      Read more about automatic deployment here.

    • wasp telemetry displays the status of telemetry.

      $ wasp telemetry

      Telemetry is currently: ENABLED
      Telemetry cache directory: /home/user/.cache/wasp/telemetry/
      Last time telemetry data was sent for this project: 2021-05-27 09:21:16.79537226 UTC
      Our telemetry is anonymized and very limited in its scope: check https://wasp-lang.dev/docs/telemetry for more details.

    • wasp deps lists the dependencies that Wasp uses in your project.

    • wasp info provides basic details about the current Wasp project.

    • wasp studio shows you an graphical overview of your application in a graph: pages, queries, actions, data model etc.

    Database Commands​

    Wasp provides a suite of commands for managing the database. These commands all begin with db and primarily execute Prisma commands behind the scenes.

    • wasp db migrate-dev synchronizes the development database with the current state of the schema (entities). If there are any changes in the schema, it generates a new migration and applies any pending migrations to the database.

      • The --name foo option allows you to specify a name for the migration, while the --create-only option lets you create an empty migration without applying it.

    • wasp db studio opens the GUI for inspecting your database.

    Bash Completion​

    To set up Bash completion, run the wasp completion command and follow the instructions.

    Miscellaneous Commands​

    • wasp version displays the current version of the CLI.

      $ wasp version

      0.12.0

      If you wish to install/switch to the latest version of Wasp, do:
      curl -sSL https://get.wasp-lang.dev/installer.sh | sh -s

      If you want specific x.y.z version of Wasp, do:
      curl -sSL https://get.wasp-lang.dev/installer.sh | sh -s -- -v x.y.z

      Check https://github.com/wasp-lang/wasp/releases for the list of valid versions, including the latest one.

    • wasp uninstall removes Wasp from your system.

      $ wasp uninstall

      🐝 --- Uninstalling Wasp ... ------------------------------------------------------

       We will remove the following directories:
         {home}/.local/share/wasp-lang/
         {home}/.cache/wasp/

       We will also remove the following files:
         {home}/.local/bin/wasp

       Are you sure you want to continue? [y/N]
       y

       ✅ --- Uninstalled Wasp -----------------------------------------------------------
    - - +
    +
    Version: 0.13.0

    CLI Reference

    This guide provides an overview of the Wasp CLI commands, arguments, and options.

    Overview​

    Once installed, you can use the wasp command from your command line.

    If you run the wasp command without any arguments, it will show you a list of available commands and their descriptions:

    USAGE
      wasp <command> [command-args]

    COMMANDS
      GENERAL
        new [<name>] [args]   Creates a new Wasp project. Run it without arguments for interactive mode.
          OPTIONS:
            -t|--template <template-name>
               Check out the templates list here: https://github.com/wasp-lang/starters

        new:ai <app-name> <app-description> [<config-json>]
          Uses AI to create a new Wasp project just based on the app name and the description.
          You can do the same thing with `wasp new` interactively.
          Run `wasp new:ai` for more info.

        version               Prints current version of CLI.
        waspls                Run Wasp Language Server. Add --help to get more info.
        completion            Prints help on bash completion.
        uninstall             Removes Wasp from your system.
      IN PROJECT
        start                 Runs Wasp app in development mode, watching for file changes.
        start db              Starts managed development database for you.
        db <db-cmd> [args]    Executes a database command. Run 'wasp db' for more info.
        clean                 Deletes all generated code, all cached artifacts, and the node_modules dir.
                              Wasp equivalent of 'have you tried closing and opening it again?'.
        build                 Generates full web app code, ready for deployment. Use when deploying or ejecting.
        deploy                Deploys your Wasp app to cloud hosting providers.
        telemetry             Prints telemetry status.
        deps                  Prints the dependencies that Wasp uses in your project.
        dockerfile            Prints the contents of the Wasp generated Dockerfile.
        info                  Prints basic information about the current Wasp project.
        test                  Executes tests in your project.
        studio                (experimental) GUI for inspecting your Wasp app.

    EXAMPLES
      wasp new MyApp
      wasp start
      wasp db migrate-dev

    Docs: https://wasp-lang.dev/docs
    Discord (chat): https://discord.gg/rzdnErX
    Newsletter: https://wasp-lang.dev/#signup

    Commands​

    Creating a New Project​

    • Use wasp new to start the interactive mode for setting up a new Wasp project.

      This will prompt you to input the project name and to select a template. The chosen template will then be used to generate the project directory with the specified name.

      $ wasp new
      Enter the project name (e.g. my-project) ▸ MyFirstProject
      Choose a starter template
      [1] basic (default)
          Simple starter template with a single page.
      [2] todo-ts
          Simple but well-rounded Wasp app implemented with Typescript & full-stack type safety.
      [3] saas
          Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check out https://opensaas.sh/ for more details.
      [4] embeddings
          Comes with code for generating vector embeddings and performing vector similarity search.
      [5] ai-generated
          🤖 Describe an app in a couple of sentences and have Wasp AI generate initial code for you. (experimental)
      ▸ 1

      🐝 --- Creating your project from the "basic" template... -------------------------

      Created new Wasp app in ./MyFirstProject directory!

      To run your new app, do:
          cd MyFirstProject
          wasp db start

    • To skip the interactive mode and create a new Wasp project with the default template, use wasp new <project-name>.

      $ wasp new MyFirstProject
      🐝 --- Creating your project from the "basic" template... -------------------------

      Created new Wasp app in ./MyFirstProject directory!

      To run your new app, do:
         cd MyFirstProject
         wasp db start

    Project Commands​

    • wasp start launches the Wasp app in development mode. It automatically opens a browser tab with your application running and watches for any changes to .wasp or files in src/ to automatically reflect in the browser. It also shows messages from the web app, the server and the database on stdout/stderr.

    • wasp start db starts the database for you. This can be very handy since you don't need to spin up your own database or provide its connection URL to the Wasp app.

    • wasp clean removes all generated code and other cached artifacts. If using SQlite, it also deletes the SQlite database. Think of this as the Wasp version of the classic "turn it off and on again" solution.

      $ wasp clean

      🐝 --- Deleting the .wasp/ directory... -------------------------------------------

      ✅ --- Deleted the .wasp/ directory. ----------------------------------------------

      🐝 --- Deleting the node_modules/ directory... ------------------------------------

      ✅ --- Deleted the node_modules/ directory. ---------------------------------------

    • wasp build generates the complete web app code, which is ready for deployment. Use this command when you're deploying or ejecting. The generated code is stored in the .wasp/build folder.

    • wasp deploy makes it easy to get your app hosted on the web.

      Currently, Wasp offers support for Fly.io. If you prefer a different hosting provider, feel free to let us know on Discord or submit a PR by updating this TypeScript app.

      Read more about automatic deployment here.

    • wasp telemetry displays the status of telemetry.

      $ wasp telemetry

      Telemetry is currently: ENABLED
      Telemetry cache directory: /home/user/.cache/wasp/telemetry/
      Last time telemetry data was sent for this project: 2021-05-27 09:21:16.79537226 UTC
      Our telemetry is anonymized and very limited in its scope: check https://wasp-lang.dev/docs/telemetry for more details.

    • wasp deps lists the dependencies that Wasp uses in your project.

    • wasp info provides basic details about the current Wasp project.

    • wasp studio shows you an graphical overview of your application in a graph: pages, queries, actions, data model etc.

    Database Commands​

    Wasp provides a suite of commands for managing the database. These commands all begin with db and primarily execute Prisma commands behind the scenes.

    • wasp db migrate-dev synchronizes the development database with the current state of the schema (entities). If there are any changes in the schema, it generates a new migration and applies any pending migrations to the database.

      • The --name foo option allows you to specify a name for the migration, while the --create-only option lets you create an empty migration without applying it.

    • wasp db studio opens the GUI for inspecting your database.

    Bash Completion​

    To set up Bash completion, run the wasp completion command and follow the instructions.

    Miscellaneous Commands​

    • wasp version displays the current version of the CLI.

      $ wasp version

      0.12.0

      If you wish to install/switch to the latest version of Wasp, do:
      curl -sSL https://get.wasp-lang.dev/installer.sh | sh -s

      If you want specific x.y.z version of Wasp, do:
      curl -sSL https://get.wasp-lang.dev/installer.sh | sh -s -- -v x.y.z

      Check https://github.com/wasp-lang/wasp/releases for the list of valid versions, including the latest one.

    • wasp uninstall removes Wasp from your system.

      $ wasp uninstall

      🐝 --- Uninstalling Wasp ... ------------------------------------------------------

       We will remove the following directories:
         {home}/.local/share/wasp-lang/
         {home}/.cache/wasp/

       We will also remove the following files:
         {home}/.local/bin/wasp

       Are you sure you want to continue? [y/N]
       y

       ✅ --- Uninstalled Wasp -----------------------------------------------------------
    + + \ No newline at end of file diff --git a/docs/general/language.html b/docs/general/language.html index 9520fda89f..33ccf00fe1 100644 --- a/docs/general/language.html +++ b/docs/general/language.html @@ -19,15 +19,15 @@ - - + + -
    -
    Version: 0.13.0

    Wasp Language (.wasp)

    Wasp language (what you write in .wasp files) is a declarative, statically typed, domain-specific language (DSL).

    It is a quite simple language, closer to JSON, CSS or SQL than to e.g. Javascript or Python, since it is not a general programming language, but more of a configuration language.

    It is pretty intuitive to learn (there isn't much to learn really!) and you can probably do just fine without reading this page and learning from the rest of the docs as you go, but if you want a bit more formal definition and deeper understanding of how it works, then read on!

    Declarations​

    The central point of Wasp language are declarations, and Wasp code is at the end just a bunch of declarations, each of them describing a part of your web app.

    app MyApp {
      title: "My app"
    }

    route RootRoute { path: "/", to: DashboardPage }

    page DashboardPage {
      component: import { DashboardPage } from "@src/Dashboard.jsx"
    }

    In the example above we described a web app via three declarations: app MyApp { ... }, route RootRoute { ... } and page DashboardPage { ... }.

    Syntax for writing a declaration is <declaration_type> <declaration_name> <declaration_body>, where:

    • <declaration_type> is one of the declaration types offered by Wasp (app, route, ...)
    • <declaration_name> is an identifier chosen by you to name this specific declaration
    • <declaration_body> is the value/definition of the declaration itself, which has to match the specific declaration body type expected by the chosen declaration type.

    So, for app declaration above, we have:

    • declaration type app
    • declaration name MyApp (we could have used any other identifier, like foobar, foo_bar, or hi3Ho)
    • declaration body { title: "My app" }, which is a dictionary with field title that has string value. +
      +
      Version: 0.13.0

      Wasp Language (.wasp)

      Wasp language (what you write in .wasp files) is a declarative, statically typed, domain-specific language (DSL).

      It is a quite simple language, closer to JSON, CSS or SQL than to e.g. Javascript or Python, since it is not a general programming language, but more of a configuration language.

      It is pretty intuitive to learn (there isn't much to learn really!) and you can probably do just fine without reading this page and learning from the rest of the docs as you go, but if you want a bit more formal definition and deeper understanding of how it works, then read on!

      Declarations​

      The central point of Wasp language are declarations, and Wasp code is at the end just a bunch of declarations, each of them describing a part of your web app.

      app MyApp {
        title: "My app"
      }

      route RootRoute { path: "/", to: DashboardPage }

      page DashboardPage {
        component: import { DashboardPage } from "@src/Dashboard.jsx"
      }

      In the example above we described a web app via three declarations: app MyApp { ... }, route RootRoute { ... } and page DashboardPage { ... }.

      Syntax for writing a declaration is <declaration_type> <declaration_name> <declaration_body>, where:

      • <declaration_type> is one of the declaration types offered by Wasp (app, route, ...)
      • <declaration_name> is an identifier chosen by you to name this specific declaration
      • <declaration_body> is the value/definition of the declaration itself, which has to match the specific declaration body type expected by the chosen declaration type.

      So, for app declaration above, we have:

      • declaration type app
      • declaration name MyApp (we could have used any other identifier, like foobar, foo_bar, or hi3Ho)
      • declaration body { title: "My app" }, which is a dictionary with field title that has string value. Type of this dictionary is in line with the declaration body type of the app declaration type. If we provided something else, e.g. changed title to little, we would get a type error from Wasp compiler since that does not match the expected type of the declaration body for app.

      Each declaration has a meaning behind it that describes how your web app should behave and function.

      All the other types in Wasp language (primitive types (string, number), composite types (dict, list), enum types (DbSystem), ...) are used to define the declaration bodies.

      Complete List of Wasp Types​

      Wasp's type system can be divided into two main categories of types: fundamental types and domain types.

      While fundamental types are here to be basic building blocks of a language and are very similar to what you would see in other popular languages, domain types are what make Wasp special, as they model the concepts of a web app like page, route and similar.

      • Fundamental types (source of truth)
        • Primitive types
          • string ("foo", "they said: \"hi\"")
          • bool (true, false)
          • number (12, 14.5)
          • declaration reference (name of existing declaration: TaskPage, updateTask)
          • ExtImport (external import) (import Foo from "@src/bar.js", import { Smth } from "@src/a/b.js")
            • The path has to start with "@src". The rest is relative to the src directory.
            • Import has to be a default import import Foo or a single named import import { Foo }.
          • json ({=json { a: 5, b: ["hi"] } json=})
          • psl (Prisma Schema Language) ({=psl <psl data model syntax> psl=})
        • Composite types
          • dict (dictionary) ({ a: 5, b: "foo" })
          • list ([1, 2, 3])
          • tuple ((1, "bar"), (2, 4, true))
            • Tuples can be of size 2, 3 and 4.
      • Domain types (source of truth)
        • Declaration types
          • action
          • api
          • apiNamespace
          • app
          • entity
          • job
          • page
          • query
          • route
          • crud
        • Enum types
          • DbSystem
          • HttpMethod
          • JobExecutor
          • EmailProvider

      You can find more details about each of the domain types, both regarding their body types and what they mean, in the corresponding doc pages covering their features.

      - - + + \ No newline at end of file diff --git a/docs/migrate-from-0-11-to-0-12.html b/docs/migrate-from-0-11-to-0-12.html index d4226df34f..69e2ab70ef 100644 --- a/docs/migrate-from-0-11-to-0-12.html +++ b/docs/migrate-from-0-11-to-0-12.html @@ -19,12 +19,12 @@ - - + + -
      -
      Version: 0.13.0

      Migration from 0.11.X to 0.12.X

      The latest version of Wasp is 0.13.X

      To fully migrate from 0.11.X to the latest version of Wasp, you should first migrate to 0.12.X and then to 0.13.X.

      Make sure to read the migration guide from 0.12.X to 0.13.X after you finish this one.

      What's new in Wasp 0.12.0?​

      New project structure​

      Here's a file tree of a fresh Wasp project created with the previous version of Wasp. +

      +
      Version: 0.13.0

      Migration from 0.11.X to 0.12.X

      The latest version of Wasp is 0.13.X

      To fully migrate from 0.11.X to the latest version of Wasp, you should first migrate to 0.12.X and then to 0.13.X.

      Make sure to read the migration guide from 0.12.X to 0.13.X after you finish this one.

      What's new in Wasp 0.12.0?​

      New project structure​

      Here's a file tree of a fresh Wasp project created with the previous version of Wasp. More precisely, this is what you'll get if you run wasp new myProject using Wasp 0.11.x:

      .
      ├── .gitignore
      ├── main.wasp
      ├── src
      │   ├── client
      │   │   ├── Main.css
      │   │   ├── MainPage.jsx
      │   │   ├── react-app-env.d.ts
      │   │   ├── tsconfig.json
      │   │   └── waspLogo.png
      │   ├── server
      │   │   └── tsconfig.json
      │   ├── shared
      │   │   └── tsconfig.json
      │   └── .waspignore
      └── .wasproot

      Compare that with the file tree of a fresh Wasp project created with Wasp 0.12.0. In other words, this is what you will get by running wasp new myProject from this point onwards:

      .
      ├── .gitignore
      ├── main.wasp
      ├── package.json
      ├── public
      │   └── .gitkeep
      ├── src
      │   ├── Main.css
      │   ├── MainPage.jsx
      │   ├── queries.ts
      │   ├── vite-env.d.ts
      │   ├── .waspignore
      │   └── waspLogo.png
      ├── tsconfig.json
      ├── vite.config.ts
      └── .wasproot

      The main differences are:

      • The server/client code separation is no longer necessary. You can now organize @@ -56,7 +56,7 @@ src/server), you are now free to reorganize your project however you think is best, as long as you keep all the source files in the src/ directory.

        This section is optional, but if you didn't like the server/client separation, now's the perfect time to change it.

        For example, if your src dir looked like this:

        src
        │
        ├── client
        │   ├── Dashboard.tsx
        │   ├── Login.tsx
        │   ├── MainPage.tsx
        │   ├── Register.tsx
        │   ├── Task.css
        │   ├── TaskLisk.tsx
        │   ├── Task.tsx
        │   └── User.tsx
        ├── server
        │   ├── taskActions.ts
        │   ├── taskQueries.ts
        │   ├── userActions.ts
        │   └── userQueries.ts
        └── shared
            └── utils.ts

        you can now change it to a feature-based structure (which we recommend for any project that is not very small):

        src
        │
        ├── task
        │   ├── actions.ts    -- former taskActions.ts
        │   ├── queries.ts    -- former taskQueries.ts
        │   ├── Task.css
        │   ├── TaskLisk.tsx
        │   └── Task.tsx
        ├── user
        │   ├── actions.ts    -- former userActions.ts
        │   ├── Dashboard.tsx
        │   ├── Login.tsx
        │   ├── queries.ts    -- former userQueries.ts
        │   ├── Register.tsx
        │   └── User.tsx
        ├── MainPage.tsx
        └── utils.ts

        Appendix​

        Example Data Migration Functions​

        The migration functions provided below are written with the typical use cases in mind and you can use them as-is. If your setup requires additional logic, you can use them as a good starting point and modify them to your needs.

        Note that all of the functions below are written to be idempotent, meaning that running a function multiple times can't hurt. This allows executing a function again in case only a part of the previous execution succeeded and also means that accidentally running it one time too much won't have any negative effects. We recommend you keep your data migration functions idempotent.

        Username & Password​

        To successfully migrate the users using the Username & Password auth method, you will need to do two things:

        1. Migrate the user data

          Username & Password data migration function
          main.wasp
          api migrateUsernameAndPassword {
            httpRoute: (GET, "/migrate-username-and-password"),
            fn: import { migrateUsernameAndPasswordHandler } from "@src/migrateToNewAuth",
            entities: []
          }
          src/migrateToNewAuth.ts
          import { prisma } from "wasp/server";
          import { type ProviderName, type UsernameProviderData } from "wasp/server/auth";
          import { MigrateUsernameAndPassword } from "wasp/server/api";

          export const migrateUsernameAndPasswordHandler: MigrateUsernameAndPassword =
            async (_req, res) => {
              const result = await migrateUsernameAuth();

              res.status(200).json({ message: "Migrated users to the new auth", result });
            };

          async function migrateUsernameAuth(): Promise<{
            numUsersAlreadyMigrated: number;
            numUsersNotUsingThisAuthMethod: number;
            numUsersMigratedSuccessfully: number;
          }> {
            const users = await prisma.user.findMany({
              include: {
                auth: true,
              },
            });

            const result = {
              numUsersAlreadyMigrated: 0,
              numUsersNotUsingThisAuthMethod: 0,
              numUsersMigratedSuccessfully: 0,
            };

            for (const user of users) {
              if (user.auth) {
                result.numUsersAlreadyMigrated++;
                console.log("Skipping user (already migrated) with id:", user.id);
                continue;
              }

              if (!user.username || !user.password) {
                result.numUsersNotUsingThisAuthMethod++;
                console.log("Skipping user (not using username auth) with id:", user.id);
                continue;
              }

              const providerData: UsernameProviderData = {
                hashedPassword: user.password,
              };
              const providerName: ProviderName = "username";

              await prisma.auth.create({
                data: {
                  identities: {
                    create: {
                      providerName,
                      providerUserId: user.username.toLowerCase(),
                      providerData: JSON.stringify(providerData),
                    },
                  },
                  user: {
                    connect: {
                      id: user.id,
                    },
                  },
                },
              });
              result.numUsersMigratedSuccessfully++;
            }

            return result;
          }

        2. Provide a way for users to migrate their password

          There is a breaking change between the old and the new auth in the way the password is hashed. This means that users will need to migrate their password after the migration, as the old password will no longer work.

          Since the only way users using username and password as a login method can verify their identity is by providing both their username and password (there is no email or any other info, unless you asked for it and stored it explicitly), we need to provide them a way to exchange their old password for a new password. One way to handle this is to inform them about the need to migrate their password (on the login page) and provide a custom page to migrate the password.

        Steps to create a custom page for migrating the password

        1. You will need to install the secure-password and sodium-native packages to use the old hashing algorithm:

          npm install secure-password@4.0.0 sodium-native@3.3.0 --save-exact

          Make sure to save the exact versions of the packages.

        2. Then you'll need to create a new page in your app where users can migrate their password. You can use the following code as a starting point:

        main.wasp
        route MigratePasswordRoute { path: "/migrate-password", to: MigratePassword }
        page MigratePassword {
          component: import { MigratePasswordPage } from "@src/pages/MigratePassword"
        }
        src/pages/MigratePassword.jsx
        import {
          FormItemGroup,
          FormLabel,
          FormInput,
          FormError,
        } from "wasp/client/auth";
        import { useForm } from "react-hook-form";
        import { migratePassword } from "wasp/client/operations";
        import { useState } from "react";

        export function MigratePasswordPage() {
          const [successMessage, setSuccessMessage] = useState(null);
          const [errorMessage, setErrorMessage] = useState(null);
          const form = useForm();

          const onSubmit = form.handleSubmit(async (data) => {
            try {
              const result = await migratePassword(data);
              setSuccessMessage(result.message);
            } catch (e) {
              console.error(e);
              if (e instanceof Error) {
                setErrorMessage(e.message);
              }
            }
          });

          return (
            <div style={{
              maxWidth: "400px",
              margin: "auto",
            }}>
              <h1>Migrate your password</h1>
              <p>
                If you have an account on the old version of the website, you can
                migrate your password to the new version.
              </p>
              {successMessage && <div>{successMessage}</div>}
              {errorMessage && <FormError>{errorMessage}</FormError>}
              <form onSubmit={onSubmit}>
                <FormItemGroup>
                  <FormLabel>Username</FormLabel>
                  <FormInput
                    {...form.register("username", {
                      required: "Username is required",
                    })}
                  />
                  <FormError>{form.formState.errors.username?.message}</FormError>
                </FormItemGroup>
                <FormItemGroup>
                  <FormLabel>Password</FormLabel>
                  <FormInput
                    {...form.register("password", {
                      required: "Password is required",
                    })}
                    type="password"
                  />
                  <FormError>{form.formState.errors.password?.message}</FormError>
                </FormItemGroup>
                <button type="submit">Migrate password</button>
              </form>
            </div>
          );
        }
        1. Finally, you will need to create a new operation in your app to handle the password migration. You can use the following code as a starting point:
        main.wasp
        action migratePassword {
          fn: import { migratePassword } from "@src/auth",
          entities: []
        }
        src/auth.js
        import SecurePassword from "secure-password";
        import { HttpError } from "wasp/server";
        import {
          createProviderId,
          deserializeAndSanitizeProviderData,
          findAuthIdentity,
          updateAuthIdentityProviderData,
        } from "wasp/server/auth";

        export const migratePassword = async ({ password, username }, _context) => {
          const providerId = createProviderId("username", username);
          const authIdentity = await findAuthIdentity(providerId);

          if (!authIdentity) {
            throw new HttpError(400, "Something went wrong");
          }

          const providerData = deserializeAndSanitizeProviderData(
            authIdentity.providerData
          );

          try {
            const SP = new SecurePassword();

            // This will verify the password using the old algorithm
            const result = await SP.verify(
              Buffer.from(password),
              Buffer.from(providerData.hashedPassword, "base64")
            );

            if (result !== SecurePassword.VALID) {
              throw new HttpError(400, "Something went wrong");
            }

            // This will hash the password using the new algorithm and update the
            // provider data in the database.
            await updateAuthIdentityProviderData(providerId, providerData, {
              hashedPassword: password,
            });
          } catch (e) {
            throw new HttpError(400, "Something went wrong");
          }

          return {
            message: "Password migrated successfully.",
          };
        };

        Email​

        To successfully migrate the users using the Email auth method, you will need to do two things:

        1. Migrate the user data

          Email data migration function
          main.wasp
          api migrateEmail {
            httpRoute: (GET, "/migrate-email"),
            fn: import { migrateEmailHandler } from "@src/migrateToNewAuth",
            entities: []
          }
          src/migrateToNewAuth.ts
          import { prisma } from "wasp/server";
          import { type ProviderName, type EmailProviderData } from "wasp/server/auth";
          import { MigrateEmail } from "wasp/server/api";

          export const migrateEmailHandler: MigrateEmail =
            async (_req, res) => {
              const result = await migrateEmailAuth();

              res.status(200).json({ message: "Migrated users to the new auth", result });
            };

          async function migrateEmailAuth(): Promise<{
            numUsersAlreadyMigrated: number;
            numUsersNotUsingThisAuthMethod: number;
            numUsersMigratedSuccessfully: number;
          }> {
            const users = await prisma.user.findMany({
              include: {
                auth: true,
              },
            });

            const result = {
              numUsersAlreadyMigrated: 0,
              numUsersNotUsingThisAuthMethod: 0,
              numUsersMigratedSuccessfully: 0,
            };

            for (const user of users) {
              if (user.auth) {
                result.numUsersAlreadyMigrated++;
                console.log("Skipping user (already migrated) with id:", user.id);
                continue;
              }

              if (!user.email || !user.password) {
                result.numUsersNotUsingThisAuthMethod++;
                console.log("Skipping user (not using email auth) with id:", user.id);
                continue;
              }

              const providerData: EmailProviderData = {
                isEmailVerified: user.isEmailVerified,
                emailVerificationSentAt:
                  user.emailVerificationSentAt?.toISOString() ?? null,
                passwordResetSentAt: user.passwordResetSentAt?.toISOString() ?? null,
                hashedPassword: user.password,
              };
              const providerName: ProviderName = "email";

              await prisma.auth.create({
                data: {
                  identities: {
                    create: {
                      providerName,
                      providerUserId: user.email,
                      providerData: JSON.stringify(providerData),
                    },
                  },
                  user: {
                    connect: {
                      id: user.id,
                    },
                  },
                },
              });
              result.numUsersMigratedSuccessfully++;
            }

            return result;
          }

        2. Ask the users to reset their password

          There is a breaking change between the old and the new auth in the way the password is hashed. This means that users will need to reset their password after the migration, as the old password will no longer work.

          It would be best to notify your users about this change and put a notice on your login page to request a password reset.

        Google & GitHub​

        Google & GitHub data migration functions
        main.wasp
        api migrateGoogle {
          httpRoute: (GET, "/migrate-google"),
          fn: import { migrateGoogleHandler } from "@src/migrateToNewAuth",
          entities: []
        }

        api migrateGithub {
          httpRoute: (GET, "/migrate-github"),
          fn: import { migrateGithubHandler } from "@src/migrateToNewAuth",
          entities: []
        }
        src/migrateToNewAuth.ts
        import { prisma } from "wasp/server";
        import { MigrateGoogle, MigrateGithub } from "wasp/server/api";

        export const migrateGoogleHandler: MigrateGoogle =
          async (_req, res) => {
            const result = await createSocialLoginMigration("google");

            res.status(200).json({ message: "Migrated users to the new auth", result });
          };

        export const migrateGithubHandler: MigrateGithub =
          async (_req, res) => {
            const result = await createSocialLoginMigration("github");

            res.status(200).json({ message: "Migrated users to the new auth", result });
          };

        async function createSocialLoginMigration(
          providerName: "google" | "github"
        ): Promise<{
          numUsersAlreadyMigrated: number;
          numUsersNotUsingThisAuthMethod: number;
          numUsersMigratedSuccessfully: number;
        }> {
          const users = await prisma.user.findMany({
            include: {
              auth: true,
              externalAuthAssociations: true,
            },
          });

          const result = {
            numUsersAlreadyMigrated: 0,
            numUsersNotUsingThisAuthMethod: 0,
            numUsersMigratedSuccessfully: 0,
          };

          for (const user of users) {
            if (user.auth) {
              result.numUsersAlreadyMigrated++;
              console.log("Skipping user (already migrated) with id:", user.id);
              continue;
            }

            const provider = user.externalAuthAssociations.find(
              (provider) => provider.provider === providerName
            );

            if (!provider) {
              result.numUsersNotUsingThisAuthMethod++;
              console.log(`Skipping user (not using ${providerName} auth) with id:`, user.id);
              continue;
            }

            await prisma.auth.create({
              data: {
                identities: {
                  create: {
                    providerName,
                    providerUserId: provider.providerId,
                    providerData: JSON.stringify({}),
                  },
                },
                user: {
                  connect: {
                    id: user.id,
                  },
                },
              },
            });
            result.numUsersMigratedSuccessfully++;
          }

          return result;
        }
      - - + + \ No newline at end of file diff --git a/docs/migrate-from-0-12-to-0-13.html b/docs/migrate-from-0-12-to-0-13.html index 72d5ac7cbc..4ccaa86a06 100644 --- a/docs/migrate-from-0-12-to-0-13.html +++ b/docs/migrate-from-0-12-to-0-13.html @@ -19,13 +19,13 @@ - - + + -
      -
      Version: 0.13.0

      Migration from 0.12.X to 0.13.X

      Are you on 0.11.X or earlier?

      This guide only covers the migration from 0.12.X to 0.13.X. If you are migrating from 0.11.X or earlier, please read the migration guide from 0.11.X to 0.12.X first.

      What's new in 0.13.0?​

      OAuth providers got an overhaul​

      Wasp 0.13.0 switches away from using Passport for our OAuth providers in favor of Arctic from the Lucia ecosystem. This change simplifies the codebase and makes it easier to add new OAuth providers in the future.

      We added Keycloak as an OAuth provider​

      Wasp now supports using Keycloak as an OAuth provider.

      How to migrate?​

      Migrate your OAuth setup​

      We had to make some breaking changes to upgrade the OAuth setup to the new Arctic lib.

      Follow the steps below to migrate:

      1. Define the WASP_SERVER_URL server env variable

        In 0.13.0 Wasp introduces a new server env variable WASP_SERVER_URL that you need to define. This is the URL of your Wasp server and it's used to generate the redirect URL for the OAuth providers.

        Server env variables
        WASP_SERVER_URL=https://your-wasp-server-url.com

        In development, Wasp sets the WASP_SERVER_URL to http://localhost:3001 by default.

        Migrating a deployed app

        If you are migrating a deployed app, you will need to define the WASP_SERVER_URL server env variable in your deployment environment.

        Read more about setting env variables in production here.

      2. Update the redirect URLs for the OAuth providers

        The redirect URL for the OAuth providers has changed. You will need to update the redirect URL for the OAuth providers in the provider's dashboard.

        {clientUrl}/auth/login/{provider}

        Check the new redirect URLs for Google and GitHub in Wasp's docs.

      3. Update the configFn for the OAuth providers

        If you didn't use the configFn option, you can skip this step.

        If you used the configFn to configure the scope for the OAuth providers, you will need to rename the scope property to scopes.

        Also, the object returned from configFn no longer needs to include the Client ID and the Client Secret. You can remove them from the object that configFn returns.

        google.ts
        export function getConfig() {
            return {
                clientID: process.env.GOOGLE_CLIENT_ID,
                clientSecret: process.env.GOOGLE_CLIENT_SECRET,
                scope: ['profile', 'email'],
            }
        }

      4. Update the userSignupFields fields to use the new profile format

        If you didn't use the userSignupFields option, you can skip this step.

        The data format for the profile that you receive from the OAuth providers has changed. You will need to update your code to reflect this change.

        google.ts
        import { defineUserSignupFields } from 'wasp/server/auth'

        export const userSignupFields = defineUserSignupFields({
            displayName: (data: any) => data.profile.displayName,
        })

        Wasp now directly forwards what it receives from the OAuth providers. You can check the data format for Google and GitHub in Wasp's docs.

      That's it!

      You should now be able to run your app with the new Wasp 0.13.0.

      - - +
      +
      Version: 0.13.0

      Migration from 0.12.X to 0.13.X

      Are you on 0.11.X or earlier?

      This guide only covers the migration from 0.12.X to 0.13.X. If you are migrating from 0.11.X or earlier, please read the migration guide from 0.11.X to 0.12.X first.

      What's new in 0.13.0?​

      OAuth providers got an overhaul​

      Wasp 0.13.0 switches away from using Passport for our OAuth providers in favor of Arctic from the Lucia ecosystem. This change simplifies the codebase and makes it easier to add new OAuth providers in the future.

      We added Keycloak as an OAuth provider​

      Wasp now supports using Keycloak as an OAuth provider.

      How to migrate?​

      Migrate your OAuth setup​

      We had to make some breaking changes to upgrade the OAuth setup to the new Arctic lib.

      Follow the steps below to migrate:

      1. Define the WASP_SERVER_URL server env variable

        In 0.13.0 Wasp introduces a new server env variable WASP_SERVER_URL that you need to define. This is the URL of your Wasp server and it's used to generate the redirect URL for the OAuth providers.

        Server env variables
        WASP_SERVER_URL=https://your-wasp-server-url.com

        In development, Wasp sets the WASP_SERVER_URL to http://localhost:3001 by default.

        Migrating a deployed app

        If you are migrating a deployed app, you will need to define the WASP_SERVER_URL server env variable in your deployment environment.

        Read more about setting env variables in production here.

      2. Update the redirect URLs for the OAuth providers

        The redirect URL for the OAuth providers has changed. You will need to update the redirect URL for the OAuth providers in the provider's dashboard.

        {clientUrl}/auth/login/{provider}

        Check the new redirect URLs for Google and GitHub in Wasp's docs.

      3. Update the configFn for the OAuth providers

        If you didn't use the configFn option, you can skip this step.

        If you used the configFn to configure the scope for the OAuth providers, you will need to rename the scope property to scopes.

        Also, the object returned from configFn no longer needs to include the Client ID and the Client Secret. You can remove them from the object that configFn returns.

        google.ts
        export function getConfig() {
            return {
                clientID: process.env.GOOGLE_CLIENT_ID,
                clientSecret: process.env.GOOGLE_CLIENT_SECRET,
                scope: ['profile', 'email'],
            }
        }

      4. Update the userSignupFields fields to use the new profile format

        If you didn't use the userSignupFields option, you can skip this step.

        The data format for the profile that you receive from the OAuth providers has changed. You will need to update your code to reflect this change.

        google.ts
        import { defineUserSignupFields } from 'wasp/server/auth'

        export const userSignupFields = defineUserSignupFields({
            displayName: (data: any) => data.profile.displayName,
        })

        Wasp now directly forwards what it receives from the OAuth providers. You can check the data format for Google and GitHub in Wasp's docs.

      That's it!

      You should now be able to run your app with the new Wasp 0.13.0.

      + + \ No newline at end of file diff --git a/docs/project/client-config.html b/docs/project/client-config.html index e54f885ea8..9096ccb39e 100644 --- a/docs/project/client-config.html +++ b/docs/project/client-config.html @@ -19,12 +19,12 @@ - - + + -
      -
      Version: 0.13.0

      Client Config

      You can configure the client using the client field inside the app declaration:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
          setupFn: import mySetupFunction from "@src/myClientSetupCode.js"
        }
      }

      Root Component​

      Wasp gives you the option to define a "wrapper" component for your React app.

      It can be used for a variety of purposes, but the most common ones are:

      • Defining a common layout for your application.
      • Setting up various providers that your application needs.

      Defining a Common Layout​

      Let's define a common layout for your application:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
        }
      }
      src/Root.jsx
      export default function Root({ children }) {
        return (
          <div>
            <header>
              <h1>My App</h1>
            </header>
            {children}
            <footer>
              <p>My App footer</p>
            </footer>
          </div>
        )
      }

      Setting up a Provider​

      This is how to set up various providers that your application needs:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
        }
      }
      src/Root.jsx
      import store from './store'
      import { Provider } from 'react-redux'

      export default function Root({ children }) {
        return <Provider store={store}>{children}</Provider>
      }

      As long as you render the children, you can do whatever you want in your root +

      +
      Version: 0.13.0

      Client Config

      You can configure the client using the client field inside the app declaration:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
          setupFn: import mySetupFunction from "@src/myClientSetupCode.js"
        }
      }

      Root Component​

      Wasp gives you the option to define a "wrapper" component for your React app.

      It can be used for a variety of purposes, but the most common ones are:

      • Defining a common layout for your application.
      • Setting up various providers that your application needs.

      Defining a Common Layout​

      Let's define a common layout for your application:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
        }
      }
      src/Root.jsx
      export default function Root({ children }) {
        return (
          <div>
            <header>
              <h1>My App</h1>
            </header>
            {children}
            <footer>
              <p>My App footer</p>
            </footer>
          </div>
        )
      }

      Setting up a Provider​

      This is how to set up various providers that your application needs:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          rootComponent: import Root from "@src/Root.jsx",
        }
      }
      src/Root.jsx
      import store from './store'
      import { Provider } from 'react-redux'

      export default function Root({ children }) {
        return <Provider store={store}>{children}</Provider>
      }

      As long as you render the children, you can do whatever you want in your root component.

      Read more about the root component in the API Reference.

      Setup Function​

      setupFn declares a function that Wasp executes on the client before everything else.

      Running Some Code​

      We can run any code we want in the setup function.

      For example, here's a setup function that logs a message every hour:

      src/myClientSetupCode.js
      export default async function mySetupFunction() {
        let count = 1
        setInterval(
          () => console.log(`You have been online for ${count++} hours.`),
          1000 * 60 * 60
        )
      }

      Overriding Default Behaviour for Queries​

      info

      You can change the options for a single Query using the options object, as described here.

      Wasp's useQuery hook uses react-query's useQuery hook under the hood. Since react-query comes configured with aggressive but sane default options, you most likely won't have to change those defaults for all Queries.

      If you do need to change the global defaults, you can do so inside the client setup function.

      Wasp exposes a configureQueryClient hook that lets you configure react-query's QueryClient object:

      src/myClientSetupCode.js
      import { configureQueryClient } from 'wasp/client/operations'

      export default async function mySetupFunction() {
        // ... some setup
        configureQueryClient({
          defaultOptions: {
            queries: {
              staleTime: Infinity,
            },
          },
        })
        // ... some more setup
      }

      Make sure to pass in an object expected by the QueryClient's constructor, as explained in react-query's docs.

      Read more about the setup function in the API Reference.

      Base Directory​

      If you need to serve the client from a subdirectory, you can use the baseDir option:

      main.wasp
      app MyApp {
        title: "My app",
        // ...
        client: {
          baseDir: "/my-app",
        }
      }

      This means that if you serve your app from https://example.com/my-app, the @@ -35,7 +35,7 @@ renders a custom layout:

      src/Root.jsx
      import store from './store'
      import { Provider } from 'react-redux'

      export default function Root({ children }) {
        return (
          <Provider store={store}>
            <Layout>{children}</Layout>
          </Provider>
        )
      }

      function Layout({ children }) {
        return (
          <div>
            <header>
              <h1>My App</h1>
            </header>
            {children}
            <footer>
              <p>My App footer</p>
            </footer>
          </div>
        )
      }

    • setupFn: ExtImport​

      You can use this function to perform any custom setup (e.g., setting up client-side periodic jobs).

      src/myClientSetupCode.js
      export default async function mySetupFunction() {
        // Run some code
      }

    • baseDir: String​

      If you need to serve the client from a subdirectory, you can use the baseDir option.

      If you set baseDir to /my-app for example, that will make Wasp set the basename prop of the Router to /my-app. It will also set the base option of the Vite config to /my-app.

      This means that if you serve your app from https://example.com/my-app, the router will work correctly, and all the assets will be served from https://example.com/my-app.

      Setting the correct env variable

      If you set the baseDir option, make sure that the WASP_WEB_CLIENT_URL env variable also includes that base directory.

      For example, if you are serving your app from https://example.com/my-app, the WASP_WEB_CLIENT_URL should be also set to https://example.com/my-app, and not just https://example.com.

    - - + + \ No newline at end of file diff --git a/docs/project/css-frameworks.html b/docs/project/css-frameworks.html index 78d74c5ff4..fdf5a4f770 100644 --- a/docs/project/css-frameworks.html +++ b/docs/project/css-frameworks.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    CSS Frameworks

    Tailwind​

    To enable support for Tailwind in your project, you need to add two config files — tailwind.config.cjs and postcss.config.cjs — to the root directory.

    With these files present, Wasp installs the necessary dependencies and copies your configuration to the generated project. You can then use Tailwind CSS directives in your CSS and Tailwind classes on your React components.

    tree .
    .
    ├── main.wasp
    ├── package.json
    ├── src
    │   ├── Main.css
    │   ├── MainPage.jsx
    │   ├── vite-env.d.ts
    │   └── waspLogo.png
    ├── public
    ├── tsconfig.json
    ├── vite.config.ts
    ├── postcss.config.cjs
    └── tailwind.config.cjs
    Tailwind not working?

    If you can not use Tailwind after adding the required config files, make sure to restart wasp start. This is sometimes needed to ensure that Wasp picks up the changes and enables Tailwind integration.

    Enabling Tailwind Step-by-Step​

    caution

    Make sure to use the .cjs extension for these config files, if you name them with a .js extension, Wasp will not detect them.

    1. Add ./tailwind.config.cjs.

      ./tailwind.config.cjs
      const { resolveProjectPath } = require('wasp/dev')

      /** @type {import('tailwindcss').Config} */
      module.exports = {
        content: [resolveProjectPath('./src/**/*.{js,jsx,ts,tsx}')],
        theme: {
          extend: {},
        },
        plugins: [],
      }

    2. Add ./postcss.config.cjs.

      ./postcss.config.cjs
      module.exports = {
        plugins: {
          tailwindcss: {},
          autoprefixer: {},
        },
      }

    3. Import Tailwind into your CSS file. For example, in a new project you might import Tailwind into Main.css.

      ./src/Main.css
      @tailwind base;
      @tailwind components;
      @tailwind utilities;

      /* ... */

    4. Start using Tailwind 🥳

      ./src/MainPage.jsx
      // ...

      <h1 className="text-3xl font-bold underline">
        Hello world!
      </h1>

      // ...

    Adding Tailwind Plugins​

    To add Tailwind plugins, install them as npm development dependencies and add them to the plugins list in your tailwind.config.cjs file:

    npm install -D @tailwindcss/forms
    npm install -D @tailwindcss/typography

    and also

    ./tailwind.config.cjs
    /** @type {import('tailwindcss').Config} */
    module.exports = {
      // ...
      plugins: [
        require('@tailwindcss/forms'),
        require('@tailwindcss/typography'),
      ],
      // ...
    }
    - - +
    +
    Version: 0.13.0

    CSS Frameworks

    Tailwind​

    To enable support for Tailwind in your project, you need to add two config files — tailwind.config.cjs and postcss.config.cjs — to the root directory.

    With these files present, Wasp installs the necessary dependencies and copies your configuration to the generated project. You can then use Tailwind CSS directives in your CSS and Tailwind classes on your React components.

    tree .
    .
    ├── main.wasp
    ├── package.json
    ├── src
    │   ├── Main.css
    │   ├── MainPage.jsx
    │   ├── vite-env.d.ts
    │   └── waspLogo.png
    ├── public
    ├── tsconfig.json
    ├── vite.config.ts
    ├── postcss.config.cjs
    └── tailwind.config.cjs
    Tailwind not working?

    If you can not use Tailwind after adding the required config files, make sure to restart wasp start. This is sometimes needed to ensure that Wasp picks up the changes and enables Tailwind integration.

    Enabling Tailwind Step-by-Step​

    caution

    Make sure to use the .cjs extension for these config files, if you name them with a .js extension, Wasp will not detect them.

    1. Add ./tailwind.config.cjs.

      ./tailwind.config.cjs
      const { resolveProjectPath } = require('wasp/dev')

      /** @type {import('tailwindcss').Config} */
      module.exports = {
        content: [resolveProjectPath('./src/**/*.{js,jsx,ts,tsx}')],
        theme: {
          extend: {},
        },
        plugins: [],
      }

    2. Add ./postcss.config.cjs.

      ./postcss.config.cjs
      module.exports = {
        plugins: {
          tailwindcss: {},
          autoprefixer: {},
        },
      }

    3. Import Tailwind into your CSS file. For example, in a new project you might import Tailwind into Main.css.

      ./src/Main.css
      @tailwind base;
      @tailwind components;
      @tailwind utilities;

      /* ... */

    4. Start using Tailwind 🥳

      ./src/MainPage.jsx
      // ...

      <h1 className="text-3xl font-bold underline">
        Hello world!
      </h1>

      // ...

    Adding Tailwind Plugins​

    To add Tailwind plugins, install them as npm development dependencies and add them to the plugins list in your tailwind.config.cjs file:

    npm install -D @tailwindcss/forms
    npm install -D @tailwindcss/typography

    and also

    ./tailwind.config.cjs
    /** @type {import('tailwindcss').Config} */
    module.exports = {
      // ...
      plugins: [
        require('@tailwindcss/forms'),
        require('@tailwindcss/typography'),
      ],
      // ...
    }
    + + \ No newline at end of file diff --git a/docs/project/custom-vite-config.html b/docs/project/custom-vite-config.html index f27081b1e7..09a190be84 100644 --- a/docs/project/custom-vite-config.html +++ b/docs/project/custom-vite-config.html @@ -19,13 +19,13 @@ - - + + -
    -
    Version: 0.13.0

    Custom Vite Config

    Wasp uses Vite to serve the client during development and bundling it for production. If you want to customize the Vite config, you can do that by editing the vite.config.ts file in your project root directory.

    Wasp will use your config and merge it with the default Wasp's Vite config.

    Vite config customization can be useful for things like:

    • Adding custom Vite plugins.
    • Customising the dev server.
    • Customising the build process.

    Be careful with making changes to the Vite config, as it can break the Wasp's client build process. Check out the default Vite config here to see what you can change.

    Examples​

    Below are some examples of how you can customize the Vite config.

    Changing the Dev Server Behaviour​

    If you want to stop Vite from opening the browser automatically when you run wasp start, you can do that by customizing the open option.

    vite.config.js
    export default {
      server: {
        open: false,
      },
    }

    Custom Dev Server Port​

    You have access to all of the Vite dev server options in your custom Vite config. You can change the dev server port by setting the port option.

    vite.config.js
    export default {
      server: {
        port: 4000,
      },
    }
    .env.server
    WASP_WEB_CLIENT_URL=http://localhost:4000
    Changing the dev server port

    ⚠️ Be careful when changing the dev server port, you'll need to update the WASP_WEB_CLIENT_URL env var in your .env.server file.

    Customising the Base Path​

    If you, for example, want to serve the client from a different path than /, you can do that by customizing the base option.

    vite.config.js
    export default {
      base: '/my-app/',
    }
    - - +
    +
    Version: 0.13.0

    Custom Vite Config

    Wasp uses Vite to serve the client during development and bundling it for production. If you want to customize the Vite config, you can do that by editing the vite.config.ts file in your project root directory.

    Wasp will use your config and merge it with the default Wasp's Vite config.

    Vite config customization can be useful for things like:

    • Adding custom Vite plugins.
    • Customising the dev server.
    • Customising the build process.

    Be careful with making changes to the Vite config, as it can break the Wasp's client build process. Check out the default Vite config here to see what you can change.

    Examples​

    Below are some examples of how you can customize the Vite config.

    Changing the Dev Server Behaviour​

    If you want to stop Vite from opening the browser automatically when you run wasp start, you can do that by customizing the open option.

    vite.config.js
    export default {
      server: {
        open: false,
      },
    }

    Custom Dev Server Port​

    You have access to all of the Vite dev server options in your custom Vite config. You can change the dev server port by setting the port option.

    vite.config.js
    export default {
      server: {
        port: 4000,
      },
    }
    .env.server
    WASP_WEB_CLIENT_URL=http://localhost:4000
    Changing the dev server port

    ⚠️ Be careful when changing the dev server port, you'll need to update the WASP_WEB_CLIENT_URL env var in your .env.server file.

    Customising the Base Path​

    If you, for example, want to serve the client from a different path than /, you can do that by customizing the base option.

    vite.config.js
    export default {
      base: '/my-app/',
    }
    + + \ No newline at end of file diff --git a/docs/project/customizing-app.html b/docs/project/customizing-app.html index 57fe48f474..637ef6f742 100644 --- a/docs/project/customizing-app.html +++ b/docs/project/customizing-app.html @@ -19,14 +19,14 @@ - - + + -
    -
    Version: 0.13.0

    Customizing the App

    Each Wasp project can have only one app type declaration. It is used to configure your app and its components.

    app todoApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "ToDo App",
      head: [
        "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto:300,400,500&display=swap\" />"
      ]
    }

    We'll go through some common customizations you might want to do to your app. For more details on each of the fields, check out the API Reference.

    Changing the App Title​

    You may want to change the title of your app, which appears in the browser tab, next to the favicon. You can change it by changing the title field of your app declaration:

    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "BookFace"
    }

    Adding Additional Lines to the Head​

    If you are looking to add additional style sheets or scripts to your app, you can do so by adding them to the head field of your app declaration.

    An example of adding extra style sheets and scripts:

    app myApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "My App",
      head: [  // optional
        "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto:300,400,500&display=swap\" />",
        "<script src=\"https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.3/Chart.min.js\"></script>",
        "<meta name=\"viewport\" content=\"minimum-scale=1, initial-scale=1, width=device-width\" />"
      ]
    }

    API Reference​

    app todoApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "ToDo App",
      head: [
        "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto:300,400,500&display=swap\" />"
      ],
      auth: {
        // ...
      },
      client: {
        // ...
      },
      server: {
        // ...
      },
      db: {
        // ...
      },
      emailSender: {
        // ...
      },
      webSocket: {
        // ...
      }
    }

    The app declaration has the following fields:

    Content and Communication​

    • Excellence comes from iteration. First drafts are always bad, but writing them is a vital part of the process. It's extremely difficult to avoid the slow progression of Bad -> OK -> Good -> Great -> Inspiring -> Transcendent.
    • Only wait until something is "Good" before publishing. Vue's guide originally says: "The community will help you push it further down the chain." We don't yet have that luxury, as our community isn't large enough. Still, we can't afford to invest too much time into the docs, so "Good" will have to do for now.

    Processes​

    • Ideally, you should write the docs before you implement the feature. This will help you see the feature from the user's perspective and better spot the API's deficiencies and improvement potential. If something is difficult to explain, it's most likely difficult to understand. If it is difficult to understand, there might be a better way of designing it.
    • Try not to get defensive when receiving feedback. Our writing can be very personal to us, but if we get upset with the people who help us improve it, they will either stop giving feedback or start limiting the kind of feedback they give.
    • Proofread your work before showing it to others (and use Grammarly). If you show someone work with many spelling/grammar mistakes, you'll get feedback about spelling grammar/mistakes instead of more valuable notes about whether the writing is achieving your goals.
    • When you ask people for feedback, tell reviewers:
      • What you're trying to do.
      • What your fears are.
      • Which balances you're trying to strike.
    • Do your best to come up with a good and straightforward way to say something. Again, this will help the reviewer focus on high-level issues instead of rephrasing your sentences.
    • Read and correct your text several times before submitting it (preferably with some time between the readings). This is similar to proofreading but has more to do with content and communication style than grammar. A time offset is beneficial because it removes the text from your short-term memory, helping you view it more objectively.
    • It's OK to ask AI to improve your text. Just make sure to check it and correct it. You should always sign off on the last version.
    • When someone reports a problem, there is almost always a problem, even if the solution they proposed isn't quite right. Keep asking follow-up questions to learn more.
    • People need to feel safe asking questions when contributing/reviewing content. Here's how you can do that:
      • Thank people for their contributions/reviews, even if you're feeling grumpy. For example:
        • "Great question!"
        • "Thanks for taking the time to explain. 🙂"
        • "This is actually intentional, but thanks for taking the time to contribute. 😊"
      • Listen to what people are saying and mirror if you're not sure you're understanding correctly. This can help validate people's feelings and experiences while also understanding if you're understanding them correctly.
      • Use a lot of positive and empathetic emojis. It's always better to seem a little strange than mean or impatient. This primarily applies to Wasp team members speaking to outside contributors. Since most of the core team knows each other pretty well, there's no need to go overboard with the emojis and pleasantries.
      • Kindly communicate rules/boundaries. If someone behaves in a way that's abusive/inappropriate, respond only with kindness and maturity, but also make it clear that this behavior is not acceptable and what will happen (according to the code of conduct) if they continue behaving poorly.
    • All docs must go through the review cycle, preferably with more than a single reviewer. Different people focus on different things. Some of us are great at coming up with examples, others easily come up with analogies and explain complex topics, some have a clear and concise writing style, etc. Therefore, try to get at least two or three people to review your document.

    Possible improvements​

    • Some parts of our docs don't follow all the guidelines outlined in this document. There's no need to start fixing all the issues right away. We can slowly improve the docs as we edit them.
    • We've discussed having a git repo with all the example code in the docs. This should make copying, pasting, testing, and maintaining code snippets easier.
    - - + + \ No newline at end of file diff --git a/img/.DS_Store b/img/.DS_Store deleted file mode 100644 index 1ead420217..0000000000 Binary files a/img/.DS_Store and /dev/null differ diff --git a/img/lw6/auth-discord.png b/img/lw6/auth-discord.png new file mode 100644 index 0000000000..e881cd64ab Binary files /dev/null and b/img/lw6/auth-discord.png differ diff --git a/img/lw6/auth-hooks.png b/img/lw6/auth-hooks.png new file mode 100644 index 0000000000..10edccf055 Binary files /dev/null and b/img/lw6/auth-hooks.png differ diff --git a/img/lw6/its-happening.gif b/img/lw6/its-happening.gif new file mode 100644 index 0000000000..6486f9cfa0 Binary files /dev/null and b/img/lw6/its-happening.gif differ diff --git a/img/lw6/lw6-banner.png b/img/lw6/lw6-banner.png new file mode 100644 index 0000000000..6fb1176437 Binary files /dev/null and b/img/lw6/lw6-banner.png differ diff --git a/img/lw6/lw6-join-kickoff.png b/img/lw6/lw6-join-kickoff.png new file mode 100644 index 0000000000..f4a215fa29 Binary files /dev/null and b/img/lw6/lw6-join-kickoff.png differ diff --git a/img/lw6/opensaas-banner.png b/img/lw6/opensaas-banner.png new file mode 100644 index 0000000000..9b4e898abd Binary files /dev/null and b/img/lw6/opensaas-banner.png differ diff --git a/img/lw6/prisma-split.png b/img/lw6/prisma-split.png new file mode 100644 index 0000000000..373a5a1310 Binary files /dev/null and b/img/lw6/prisma-split.png differ diff --git a/img/lw6/ts-sdk.png b/img/lw6/ts-sdk.png new file mode 100644 index 0000000000..0b4a129781 Binary files /dev/null and b/img/lw6/ts-sdk.png differ diff --git a/index.html b/index.html index a95b57656f..be7209869c 100644 --- a/index.html +++ b/index.html @@ -19,12 +19,12 @@ - - + + -
    -
    Our free SaaS starter is live on Product Hunt!

    Develop full-stack web apps faster.

    Rails-like framework for React, Node.js and Prisma. Build your app in a day and deploy it with a single CLI command.

    Works with
    ReactNodePrisma
    Backed byYC
    todoApp.wasp· Wasp config file
    app todoApp {
+
    
+
    🐝 Launch Week #6: 🐝 July 17 - 22
    Develop full-stack web apps faster.
    Rails-like framework for React, Node.js and Prisma. Build your app in a day and deploy it with a single CLI command.
     
    Works with
    ReactNodePrisma
    Backed byYC
    todoApp.wasp· Wasp config file
    app todoApp {
   title: "ToDo App",  // visible in the browser tab
   auth: { // full-stack auth out-of-the-box
     userEntity: User, 
@@ -64,7 +64,7 @@
           
    Learn more
    How does it work? 🧐
    Given a simple .wasp configuration file that describes the high-level details of your web app, and .js(x)/.css/..., source files with your unique logic, Wasp compiler generates the full source of your web app in the target stack: front-end, back-end and deployment. 

    This unique approach is what makes Wasp "smart" and gives it its super powers!
    Simple config language
    Declaratively describe high-level details of your app.
    Learn more
    Wasp CLI
    All the handy commands at your fingertips.
    Learn more
    React / Node.js / Prisma
    You are still writing 90% of the code in your favorite technologies.
    Arrivederci boilerplate
    Write only the code that matters, let Wasp handle the rest.
    Learn more
     
    React
    Show, don't tell.
    Take a look at examples - see how things work and get inspired for your next project.
    Todo App (TypeScript) ✅
    A famous To-Do list app, implemented in TypeScript.
    wasp GitHub profile picturewasp
    todo-typescript
    CoverLetterGPT 🤖
    Generate cover letters based on your CV and the job description. Powered by ChatGPT.
    vincanger GitHub profile picturevincanger
    coverlettergpt
    Realtime voting via WebSockets 🔌
    A realtime, websockets-powered voting app built with Wasp and TypeScript.
    wasp GitHub profile picturewasp
    websockets-realtime-voting
    See all examples
    Stay up to date 📬
    Be the first to know when we ship new features and updates!
    🚧 Roadmap 🚧
    Work on Wasp never stops: get a glimpse of what is coming next!
    Right behind the corner
    • Improve Prisma support (more features, IDE) 
      641
    • Add TS eDSL, next to Wasp DSL 
      551
    • Make Wasp Auth usable in external services 
      1973
    • Add more social providers to Wasp Auth 
      2016
    • Support for SSR / SSG 
      911
    • Full-Stack Modules (aka FSMs: think RoR Engines)
    Further down the road
    • Multiple targets (e.g. mobile) 
      1088
    • Automatic generation of API for Operations 
      863
    • Top-level data schema 
      642
    • Complex arch (multiple servers, clients, serverless)
    • Polyglot (Python, Rust, Go, ...) 
      1940
    • Multiple frontend libraries (Vue, Svelte, ...)
    Frequently asked questions
    For anything not covered here, join our Discord!
    
-
-
+
+
 
 
\ No newline at end of file
diff --git a/search.html b/search.html
index 3a435cd832..2703f0b4e3 100644
--- a/search.html
+++ b/search.html
@@ -19,13 +19,13 @@
 
 
 
-
-
+
+
 
 
-
    
-
    Search the documentation
    
-
-
+
    
+
    Search the documentation
    
+
+
 
 
\ No newline at end of file
diff --git a/sitemap.xml b/sitemap.xml
index bbeb7b0185..4e8305ce87 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -1 +1 @@
-https://wasp-lang.dev/blogweekly0.5https://wasp-lang.dev/blog/2019/09/01/hello-waspweekly0.5https://wasp-lang.dev/blog/2021/02/23/journey-to-ycombinatorweekly0.5https://wasp-lang.dev/blog/2021/03/02/wasp-alphaweekly0.5https://wasp-lang.dev/blog/2021/04/29/discord-bot-introductionweekly0.5https://wasp-lang.dev/blog/2021/09/01/haskell-forall-tutorialweekly0.5https://wasp-lang.dev/blog/2021/11/21/seed-roundweekly0.5https://wasp-lang.dev/blog/2021/11/22/fundraising-learningsweekly0.5https://wasp-lang.dev/blog/2021/12/02/waspelloweekly0.5https://wasp-lang.dev/blog/2021/12/21/shayne-introweekly0.5https://wasp-lang.dev/blog/2022/01/27/waspleauweekly0.5https://wasp-lang.dev/blog/2022/05/31/filip-introweekly0.5https://wasp-lang.dev/blog/2022/06/01/gitpod-hackathon-guideweekly0.5https://wasp-lang.dev/blog/2022/06/15/jobs-feature-announcementweekly0.5https://wasp-lang.dev/blog/2022/06/24/ML-code-gen-vs-coding-by-hand-futureweekly0.5https://wasp-lang.dev/blog/2022/08/15/how-to-communicate-why-your-startup-is-worth-joiningweekly0.5https://wasp-lang.dev/blog/2022/08/26/how-and-why-i-got-started-with-haskellweekly0.5https://wasp-lang.dev/blog/2022/09/02/how-to-get-started-with-haskell-in-2022weekly0.5https://wasp-lang.dev/blog/2022/09/05/dev-excuses-app-tutrialweekly0.5https://wasp-lang.dev/blog/2022/09/29/journey-to-1000-gh-starsweekly0.5https://wasp-lang.dev/blog/2022/10/28/farnance-hackathon-winnerweekly0.5https://wasp-lang.dev/blog/2022/11/15/auth-feature-announcementweekly0.5https://wasp-lang.dev/blog/2022/11/16/alpha-testing-program-post-mortemweekly0.5https://wasp-lang.dev/blog/2022/11/16/tailwind-feature-announcementweekly0.5https://wasp-lang.dev/blog/2022/11/17/hacktoberfest-wrap-upweekly0.5https://wasp-lang.dev/blog/2022/11/26/erlis-amicus-usecaseweekly0.5https://wasp-lang.dev/blog/2022/11/26/michael-curry-usecaseweekly0.5https://wasp-lang.dev/blog/2022/11/26/wasp-beta-launch-weekweekly0.5https://wasp-lang.dev/blog/2022/11/28/why-we-chose-prismaweekly0.5https://wasp-lang.dev/blog/2022/11/29/permissions-in-web-appsweekly0.5https://wasp-lang.dev/blog/2022/11/29/typescript-feature-announcementweekly0.5https://wasp-lang.dev/blog/2022/11/29/wasp-betaweekly0.5https://wasp-lang.dev/blog/2022/11/30/optimistic-update-feature-announcementweekly0.5https://wasp-lang.dev/blog/2022/12/01/beta-ide-improvementsweekly0.5https://wasp-lang.dev/blog/2022/12/08/fast-fullstack-chatgptweekly0.5https://wasp-lang.dev/blog/2023/01/11/betathon-reviewweekly0.5https://wasp-lang.dev/blog/2023/01/18/wasp-beta-update-decweekly0.5https://wasp-lang.dev/blog/2023/01/31/wasp-beta-launch-reviewweekly0.5https://wasp-lang.dev/blog/2023/02/02/no-best-frameworkweekly0.5https://wasp-lang.dev/blog/2023/02/14/amicus-indiehacker-interviewweekly0.5https://wasp-lang.dev/blog/2023/02/21/junior-developer-misconceptionsweekly0.5https://wasp-lang.dev/blog/2023/03/02/wasp-beta-update-febweekly0.5https://wasp-lang.dev/blog/2023/03/03/ten-hard-truths-junior-developers-need-to-hearweekly0.5https://wasp-lang.dev/blog/2023/03/08/building-a-full-stack-app-supabase-vs-waspweekly0.5https://wasp-lang.dev/blog/2023/03/17/new-react-docs-pretend-spas-dont-existweekly0.5https://wasp-lang.dev/blog/2023/04/11/wasp-launch-week-twoweekly0.5https://wasp-lang.dev/blog/2023/04/12/auth-uiweekly0.5https://wasp-lang.dev/blog/2023/04/13/db-start-and-seedweekly0.5https://wasp-lang.dev/blog/2023/04/17/How-I-Built-CoverLetterGPTweekly0.5https://wasp-lang.dev/blog/2023/04/27/wasp-hackathon-twoweekly0.5https://wasp-lang.dev/blog/2023/05/19/hackathon-2-reviewweekly0.5https://wasp-lang.dev/blog/2023/06/07/wasp-beta-update-may-23weekly0.5https://wasp-lang.dev/blog/2023/06/22/wasp-launch-week-threeweekly0.5https://wasp-lang.dev/blog/2023/06/27/build-your-own-twitter-agent-langchainweekly0.5https://wasp-lang.dev/blog/2023/06/28/what-can-you-build-with-waspweekly0.5https://wasp-lang.dev/blog/2023/06/29/new-wasp-lspweekly0.5https://wasp-lang.dev/blog/2023/06/30/tutorial-jamweekly0.5https://wasp-lang.dev/blog/2023/07/10/gpt-web-app-generatorweekly0.5https://wasp-lang.dev/blog/2023/07/17/how-we-built-gpt-web-app-generatorweekly0.5https://wasp-lang.dev/blog/2023/08/01/smol-ai-vs-wasp-aiweekly0.5https://wasp-lang.dev/blog/2023/08/09/build-real-time-voting-app-websockets-react-typescriptweekly0.5https://wasp-lang.dev/blog/2023/08/23/using-product-requirement-documents-generate-better-web-apps-with-aiweekly0.5https://wasp-lang.dev/blog/2023/09/17/ai-meme-generator-how-to-use-openai-function-callweekly0.5https://wasp-lang.dev/blog/2023/10/04/contributing-open-source-land-a-jobweekly0.5https://wasp-lang.dev/blog/2023/10/12/on-importance-of-naming-in-programmingweekly0.5https://wasp-lang.dev/blog/2023/10/13/wasp-launch-week-fourweekly0.5https://wasp-lang.dev/blog/2023/11/21/guide-windows-development-wasp-wslweekly0.5https://wasp-lang.dev/blog/2023/12/05/writing-rfcsweekly0.5https://wasp-lang.dev/blog/2024/01/23/wasp-launch-week-fiveweekly0.5https://wasp-lang.dev/blog/2024/01/30/open-saas-free-open-source-starter-react-nodejsweekly0.5https://wasp-lang.dev/blog/2024/04/25/first-framework-that-lets-you-visualize-react-node-app-codeweekly0.5https://wasp-lang.dev/blog/2024/05/22/how-to-get-a-web-dev-job-2024weekly0.5https://wasp-lang.dev/blog/2024/05/29/why-we-dont-have-laravel-for-javascript-yetweekly0.5https://wasp-lang.dev/blog/2024/07/03/building-selling-saas-in-5-monthsweekly0.5https://wasp-lang.dev/blog/archiveweekly0.5https://wasp-lang.dev/blog/tagsweekly0.5https://wasp-lang.dev/blog/tags/acquireweekly0.5https://wasp-lang.dev/blog/tags/agentweekly0.5https://wasp-lang.dev/blog/tags/aiweekly0.5https://wasp-lang.dev/blog/tags/authweekly0.5https://wasp-lang.dev/blog/tags/boilerplateweekly0.5https://wasp-lang.dev/blog/tags/careerweekly0.5https://wasp-lang.dev/blog/tags/chakraweekly0.5https://wasp-lang.dev/blog/tags/chatgptweekly0.5https://wasp-lang.dev/blog/tags/clean-codeweekly0.5https://wasp-lang.dev/blog/tags/cssweekly0.5https://wasp-lang.dev/blog/tags/databaseweekly0.5https://wasp-lang.dev/blog/tags/discordweekly0.5https://wasp-lang.dev/blog/tags/expressweekly0.5https://wasp-lang.dev/blog/tags/featureweekly0.5https://wasp-lang.dev/blog/tags/frameworkweekly0.5https://wasp-lang.dev/blog/tags/full-stackweekly0.5https://wasp-lang.dev/blog/tags/fullstackweekly0.5https://wasp-lang.dev/blog/tags/function-callingweekly0.5https://wasp-lang.dev/blog/tags/generateweekly0.5https://wasp-lang.dev/blog/tags/githubweekly0.5https://wasp-lang.dev/blog/tags/gitpodweekly0.5https://wasp-lang.dev/blog/tags/gptweekly0.5https://wasp-lang.dev/blog/tags/hackweekly0.5https://wasp-lang.dev/blog/tags/hackathonweekly0.5https://wasp-lang.dev/blog/tags/hacktoberfestweekly0.5https://wasp-lang.dev/blog/tags/haskellweekly0.5https://wasp-lang.dev/blog/tags/hiringweekly0.5https://wasp-lang.dev/blog/tags/indie-hackerweekly0.5https://wasp-lang.dev/blog/tags/interviewweekly0.5https://wasp-lang.dev/blog/tags/javascriptweekly0.5https://wasp-lang.dev/blog/tags/jobweekly0.5https://wasp-lang.dev/blog/tags/jobsweekly0.5https://wasp-lang.dev/blog/tags/junior-developersweekly0.5https://wasp-lang.dev/blog/tags/langchainweekly0.5https://wasp-lang.dev/blog/tags/languageweekly0.5https://wasp-lang.dev/blog/tags/laravelweekly0.5https://wasp-lang.dev/blog/tags/launch-weekweekly0.5https://wasp-lang.dev/blog/tags/mageweekly0.5https://wasp-lang.dev/blog/tags/marketingweekly0.5https://wasp-lang.dev/blog/tags/memeweekly0.5https://wasp-lang.dev/blog/tags/mlweekly0.5https://wasp-lang.dev/blog/tags/new-hireweekly0.5https://wasp-lang.dev/blog/tags/nodeweekly0.5https://wasp-lang.dev/blog/tags/nodejsweekly0.5https://wasp-lang.dev/blog/tags/open-sourceweekly0.5https://wasp-lang.dev/blog/tags/openaiweekly0.5https://wasp-lang.dev/blog/tags/optimisticweekly0.5https://wasp-lang.dev/blog/tags/pernweekly0.5https://wasp-lang.dev/blog/tags/prdweekly0.5https://wasp-lang.dev/blog/tags/prismaweekly0.5https://wasp-lang.dev/blog/tags/product-requirementweekly0.5https://wasp-lang.dev/blog/tags/product-updateweekly0.5https://wasp-lang.dev/blog/tags/programmingweekly0.5https://wasp-lang.dev/blog/tags/railsweekly0.5https://wasp-lang.dev/blog/tags/reactweekly0.5https://wasp-lang.dev/blog/tags/real-timeweekly0.5https://wasp-lang.dev/blog/tags/redditweekly0.5https://wasp-lang.dev/blog/tags/saa-sweekly0.5https://wasp-lang.dev/blog/tags/saasweekly0.5https://wasp-lang.dev/blog/tags/showcaseweekly0.5https://wasp-lang.dev/blog/tags/solopreneurweekly0.5https://wasp-lang.dev/blog/tags/startupweekly0.5https://wasp-lang.dev/blog/tags/startupsweekly0.5https://wasp-lang.dev/blog/tags/state-of-jsweekly0.5https://wasp-lang.dev/blog/tags/stripeweekly0.5https://wasp-lang.dev/blog/tags/supabaseweekly0.5https://wasp-lang.dev/blog/tags/techweekly0.5https://wasp-lang.dev/blog/tags/tech-careerweekly0.5https://wasp-lang.dev/blog/tags/tutorialweekly0.5https://wasp-lang.dev/blog/tags/typescriptweekly0.5https://wasp-lang.dev/blog/tags/updateweekly0.5https://wasp-lang.dev/blog/tags/updatesweekly0.5https://wasp-lang.dev/blog/tags/waspweekly0.5https://wasp-lang.dev/blog/tags/wasp-aiweekly0.5https://wasp-lang.dev/blog/tags/web-devweekly0.5https://wasp-lang.dev/blog/tags/web-developmentweekly0.5https://wasp-lang.dev/blog/tags/webdevweekly0.5https://wasp-lang.dev/blog/tags/websocketsweekly0.5https://wasp-lang.dev/blog/tags/windowsweekly0.5https://wasp-lang.dev/blog/tags/wslweekly0.5https://wasp-lang.dev/searchweekly0.5https://wasp-lang.dev/docs/0.11.8weekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/apisweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/deployment/cliweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/deployment/manuallyweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/deployment/overviewweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/emailweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/jobsweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/linksweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/middleware-configweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/web-socketsweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/emailweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/overviewweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/social-auth/githubweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/social-auth/googleweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/social-auth/overviewweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/uiweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/username-and-passweekly0.5https://wasp-lang.dev/docs/0.11.8/contactweekly0.5https://wasp-lang.dev/docs/0.11.8/contributingweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/backendsweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/crudweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/entitiesweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/operations/actionsweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/operations/overviewweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/operations/queriesweekly0.5https://wasp-lang.dev/docs/0.11.8/editor-setupweekly0.5https://wasp-lang.dev/docs/0.11.8/general/cliweekly0.5https://wasp-lang.dev/docs/0.11.8/general/languageweekly0.5https://wasp-lang.dev/docs/0.11.8/project/client-configweekly0.5https://wasp-lang.dev/docs/0.11.8/project/css-frameworksweekly0.5https://wasp-lang.dev/docs/0.11.8/project/custom-vite-configweekly0.5https://wasp-lang.dev/docs/0.11.8/project/customizing-appweekly0.5https://wasp-lang.dev/docs/0.11.8/project/dependenciesweekly0.5https://wasp-lang.dev/docs/0.11.8/project/env-varsweekly0.5https://wasp-lang.dev/docs/0.11.8/project/server-configweekly0.5https://wasp-lang.dev/docs/0.11.8/project/starter-templatesweekly0.5https://wasp-lang.dev/docs/0.11.8/project/static-assetsweekly0.5https://wasp-lang.dev/docs/0.11.8/project/testingweekly0.5https://wasp-lang.dev/docs/0.11.8/quick-startweekly0.5https://wasp-lang.dev/docs/0.11.8/telemetryweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/actionsweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/authweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/createweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/entitiesweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/pagesweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/project-structureweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/queriesweekly0.5https://wasp-lang.dev/docs/0.11.8/visionweekly0.5https://wasp-lang.dev/docs/0.11.8/writingguideweekly0.5https://wasp-lang.dev/docs/0.12.0weekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/apisweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/deployment/cliweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/deployment/manuallyweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/deployment/overviewweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/emailweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/jobsweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/linksweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/middleware-configweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/web-socketsweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/emailweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/entitiesweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/overviewweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/social-auth/githubweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/social-auth/googleweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/social-auth/overviewweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/uiweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/username-and-passweekly0.5https://wasp-lang.dev/docs/0.12.0/contactweekly0.5https://wasp-lang.dev/docs/0.12.0/contributingweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/backendsweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/crudweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/entitiesweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/operations/actionsweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/operations/overviewweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/operations/queriesweekly0.5https://wasp-lang.dev/docs/0.12.0/editor-setupweekly0.5https://wasp-lang.dev/docs/0.12.0/general/cliweekly0.5https://wasp-lang.dev/docs/0.12.0/general/languageweekly0.5https://wasp-lang.dev/docs/0.12.0/migrate-from-0-11-to-0-12weekly0.5https://wasp-lang.dev/docs/0.12.0/project/client-configweekly0.5https://wasp-lang.dev/docs/0.12.0/project/css-frameworksweekly0.5https://wasp-lang.dev/docs/0.12.0/project/custom-vite-configweekly0.5https://wasp-lang.dev/docs/0.12.0/project/customizing-appweekly0.5https://wasp-lang.dev/docs/0.12.0/project/dependenciesweekly0.5https://wasp-lang.dev/docs/0.12.0/project/env-varsweekly0.5https://wasp-lang.dev/docs/0.12.0/project/server-configweekly0.5https://wasp-lang.dev/docs/0.12.0/project/starter-templatesweekly0.5https://wasp-lang.dev/docs/0.12.0/project/static-assetsweekly0.5https://wasp-lang.dev/docs/0.12.0/project/testingweekly0.5https://wasp-lang.dev/docs/0.12.0/quick-startweekly0.5https://wasp-lang.dev/docs/0.12.0/telemetryweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/actionsweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/authweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/createweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/entitiesweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/pagesweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/project-structureweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/queriesweekly0.5https://wasp-lang.dev/docs/0.12.0/visionweekly0.5https://wasp-lang.dev/docs/0.12.0/wasp-ai/creating-new-appweekly0.5https://wasp-lang.dev/docs/0.12.0/wasp-ai/developing-existing-appweekly0.5https://wasp-lang.dev/docs/0.12.0/writingguideweekly0.5https://wasp-lang.dev/docsweekly0.5https://wasp-lang.dev/docs/advanced/accessing-app-configweekly0.5https://wasp-lang.dev/docs/advanced/apisweekly0.5https://wasp-lang.dev/docs/advanced/deployment/cliweekly0.5https://wasp-lang.dev/docs/advanced/deployment/manuallyweekly0.5https://wasp-lang.dev/docs/advanced/deployment/overviewweekly0.5https://wasp-lang.dev/docs/advanced/emailweekly0.5https://wasp-lang.dev/docs/advanced/jobsweekly0.5https://wasp-lang.dev/docs/advanced/linksweekly0.5https://wasp-lang.dev/docs/advanced/middleware-configweekly0.5https://wasp-lang.dev/docs/advanced/web-socketsweekly0.5https://wasp-lang.dev/docs/auth/emailweekly0.5https://wasp-lang.dev/docs/auth/entitiesweekly0.5https://wasp-lang.dev/docs/auth/overviewweekly0.5https://wasp-lang.dev/docs/auth/social-auth/githubweekly0.5https://wasp-lang.dev/docs/auth/social-auth/googleweekly0.5https://wasp-lang.dev/docs/auth/social-auth/keycloakweekly0.5https://wasp-lang.dev/docs/auth/social-auth/overviewweekly0.5https://wasp-lang.dev/docs/auth/uiweekly0.5https://wasp-lang.dev/docs/auth/username-and-passweekly0.5https://wasp-lang.dev/docs/contactweekly0.5https://wasp-lang.dev/docs/contributingweekly0.5https://wasp-lang.dev/docs/data-model/backendsweekly0.5https://wasp-lang.dev/docs/data-model/crudweekly0.5https://wasp-lang.dev/docs/data-model/entitiesweekly0.5https://wasp-lang.dev/docs/data-model/operations/actionsweekly0.5https://wasp-lang.dev/docs/data-model/operations/overviewweekly0.5https://wasp-lang.dev/docs/data-model/operations/queriesweekly0.5https://wasp-lang.dev/docs/editor-setupweekly0.5https://wasp-lang.dev/docs/general/cliweekly0.5https://wasp-lang.dev/docs/general/languageweekly0.5https://wasp-lang.dev/docs/migrate-from-0-11-to-0-12weekly0.5https://wasp-lang.dev/docs/migrate-from-0-12-to-0-13weekly0.5https://wasp-lang.dev/docs/project/client-configweekly0.5https://wasp-lang.dev/docs/project/css-frameworksweekly0.5https://wasp-lang.dev/docs/project/custom-vite-configweekly0.5https://wasp-lang.dev/docs/project/customizing-appweekly0.5https://wasp-lang.dev/docs/project/dependenciesweekly0.5https://wasp-lang.dev/docs/project/env-varsweekly0.5https://wasp-lang.dev/docs/project/server-configweekly0.5https://wasp-lang.dev/docs/project/starter-templatesweekly0.5https://wasp-lang.dev/docs/project/static-assetsweekly0.5https://wasp-lang.dev/docs/project/testingweekly0.5https://wasp-lang.dev/docs/quick-startweekly0.5https://wasp-lang.dev/docs/telemetryweekly0.5https://wasp-lang.dev/docs/tutorial/actionsweekly0.5https://wasp-lang.dev/docs/tutorial/authweekly0.5https://wasp-lang.dev/docs/tutorial/createweekly0.5https://wasp-lang.dev/docs/tutorial/entitiesweekly0.5https://wasp-lang.dev/docs/tutorial/pagesweekly0.5https://wasp-lang.dev/docs/tutorial/project-structureweekly0.5https://wasp-lang.dev/docs/tutorial/queriesweekly0.5https://wasp-lang.dev/docs/visionweekly0.5https://wasp-lang.dev/docs/wasp-ai/creating-new-appweekly0.5https://wasp-lang.dev/docs/wasp-ai/developing-existing-appweekly0.5https://wasp-lang.dev/docs/writingguideweekly0.5https://wasp-lang.dev/weekly0.5
\ No newline at end of file
+https://wasp-lang.dev/blogweekly0.5https://wasp-lang.dev/blog/2019/09/01/hello-waspweekly0.5https://wasp-lang.dev/blog/2021/02/23/journey-to-ycombinatorweekly0.5https://wasp-lang.dev/blog/2021/03/02/wasp-alphaweekly0.5https://wasp-lang.dev/blog/2021/04/29/discord-bot-introductionweekly0.5https://wasp-lang.dev/blog/2021/09/01/haskell-forall-tutorialweekly0.5https://wasp-lang.dev/blog/2021/11/21/seed-roundweekly0.5https://wasp-lang.dev/blog/2021/11/22/fundraising-learningsweekly0.5https://wasp-lang.dev/blog/2021/12/02/waspelloweekly0.5https://wasp-lang.dev/blog/2021/12/21/shayne-introweekly0.5https://wasp-lang.dev/blog/2022/01/27/waspleauweekly0.5https://wasp-lang.dev/blog/2022/05/31/filip-introweekly0.5https://wasp-lang.dev/blog/2022/06/01/gitpod-hackathon-guideweekly0.5https://wasp-lang.dev/blog/2022/06/15/jobs-feature-announcementweekly0.5https://wasp-lang.dev/blog/2022/06/24/ML-code-gen-vs-coding-by-hand-futureweekly0.5https://wasp-lang.dev/blog/2022/08/15/how-to-communicate-why-your-startup-is-worth-joiningweekly0.5https://wasp-lang.dev/blog/2022/08/26/how-and-why-i-got-started-with-haskellweekly0.5https://wasp-lang.dev/blog/2022/09/02/how-to-get-started-with-haskell-in-2022weekly0.5https://wasp-lang.dev/blog/2022/09/05/dev-excuses-app-tutrialweekly0.5https://wasp-lang.dev/blog/2022/09/29/journey-to-1000-gh-starsweekly0.5https://wasp-lang.dev/blog/2022/10/28/farnance-hackathon-winnerweekly0.5https://wasp-lang.dev/blog/2022/11/15/auth-feature-announcementweekly0.5https://wasp-lang.dev/blog/2022/11/16/alpha-testing-program-post-mortemweekly0.5https://wasp-lang.dev/blog/2022/11/16/tailwind-feature-announcementweekly0.5https://wasp-lang.dev/blog/2022/11/17/hacktoberfest-wrap-upweekly0.5https://wasp-lang.dev/blog/2022/11/26/erlis-amicus-usecaseweekly0.5https://wasp-lang.dev/blog/2022/11/26/michael-curry-usecaseweekly0.5https://wasp-lang.dev/blog/2022/11/26/wasp-beta-launch-weekweekly0.5https://wasp-lang.dev/blog/2022/11/28/why-we-chose-prismaweekly0.5https://wasp-lang.dev/blog/2022/11/29/permissions-in-web-appsweekly0.5https://wasp-lang.dev/blog/2022/11/29/typescript-feature-announcementweekly0.5https://wasp-lang.dev/blog/2022/11/29/wasp-betaweekly0.5https://wasp-lang.dev/blog/2022/11/30/optimistic-update-feature-announcementweekly0.5https://wasp-lang.dev/blog/2022/12/01/beta-ide-improvementsweekly0.5https://wasp-lang.dev/blog/2022/12/08/fast-fullstack-chatgptweekly0.5https://wasp-lang.dev/blog/2023/01/11/betathon-reviewweekly0.5https://wasp-lang.dev/blog/2023/01/18/wasp-beta-update-decweekly0.5https://wasp-lang.dev/blog/2023/01/31/wasp-beta-launch-reviewweekly0.5https://wasp-lang.dev/blog/2023/02/02/no-best-frameworkweekly0.5https://wasp-lang.dev/blog/2023/02/14/amicus-indiehacker-interviewweekly0.5https://wasp-lang.dev/blog/2023/02/21/junior-developer-misconceptionsweekly0.5https://wasp-lang.dev/blog/2023/03/02/wasp-beta-update-febweekly0.5https://wasp-lang.dev/blog/2023/03/03/ten-hard-truths-junior-developers-need-to-hearweekly0.5https://wasp-lang.dev/blog/2023/03/08/building-a-full-stack-app-supabase-vs-waspweekly0.5https://wasp-lang.dev/blog/2023/03/17/new-react-docs-pretend-spas-dont-existweekly0.5https://wasp-lang.dev/blog/2023/04/11/wasp-launch-week-twoweekly0.5https://wasp-lang.dev/blog/2023/04/12/auth-uiweekly0.5https://wasp-lang.dev/blog/2023/04/13/db-start-and-seedweekly0.5https://wasp-lang.dev/blog/2023/04/17/How-I-Built-CoverLetterGPTweekly0.5https://wasp-lang.dev/blog/2023/04/27/wasp-hackathon-twoweekly0.5https://wasp-lang.dev/blog/2023/05/19/hackathon-2-reviewweekly0.5https://wasp-lang.dev/blog/2023/06/07/wasp-beta-update-may-23weekly0.5https://wasp-lang.dev/blog/2023/06/22/wasp-launch-week-threeweekly0.5https://wasp-lang.dev/blog/2023/06/27/build-your-own-twitter-agent-langchainweekly0.5https://wasp-lang.dev/blog/2023/06/28/what-can-you-build-with-waspweekly0.5https://wasp-lang.dev/blog/2023/06/29/new-wasp-lspweekly0.5https://wasp-lang.dev/blog/2023/06/30/tutorial-jamweekly0.5https://wasp-lang.dev/blog/2023/07/10/gpt-web-app-generatorweekly0.5https://wasp-lang.dev/blog/2023/07/17/how-we-built-gpt-web-app-generatorweekly0.5https://wasp-lang.dev/blog/2023/08/01/smol-ai-vs-wasp-aiweekly0.5https://wasp-lang.dev/blog/2023/08/09/build-real-time-voting-app-websockets-react-typescriptweekly0.5https://wasp-lang.dev/blog/2023/08/23/using-product-requirement-documents-generate-better-web-apps-with-aiweekly0.5https://wasp-lang.dev/blog/2023/09/17/ai-meme-generator-how-to-use-openai-function-callweekly0.5https://wasp-lang.dev/blog/2023/10/04/contributing-open-source-land-a-jobweekly0.5https://wasp-lang.dev/blog/2023/10/12/on-importance-of-naming-in-programmingweekly0.5https://wasp-lang.dev/blog/2023/10/13/wasp-launch-week-fourweekly0.5https://wasp-lang.dev/blog/2023/11/21/guide-windows-development-wasp-wslweekly0.5https://wasp-lang.dev/blog/2023/12/05/writing-rfcsweekly0.5https://wasp-lang.dev/blog/2024/01/23/wasp-launch-week-fiveweekly0.5https://wasp-lang.dev/blog/2024/01/30/open-saas-free-open-source-starter-react-nodejsweekly0.5https://wasp-lang.dev/blog/2024/04/25/first-framework-that-lets-you-visualize-react-node-app-codeweekly0.5https://wasp-lang.dev/blog/2024/05/22/how-to-get-a-web-dev-job-2024weekly0.5https://wasp-lang.dev/blog/2024/05/29/why-we-dont-have-laravel-for-javascript-yetweekly0.5https://wasp-lang.dev/blog/2024/07/03/building-selling-saas-in-5-monthsweekly0.5https://wasp-lang.dev/blog/2024/07/15/wasp-launch-week-sixweekly0.5https://wasp-lang.dev/blog/archiveweekly0.5https://wasp-lang.dev/blog/tagsweekly0.5https://wasp-lang.dev/blog/tags/acquireweekly0.5https://wasp-lang.dev/blog/tags/agentweekly0.5https://wasp-lang.dev/blog/tags/aiweekly0.5https://wasp-lang.dev/blog/tags/authweekly0.5https://wasp-lang.dev/blog/tags/boilerplateweekly0.5https://wasp-lang.dev/blog/tags/careerweekly0.5https://wasp-lang.dev/blog/tags/chakraweekly0.5https://wasp-lang.dev/blog/tags/chatgptweekly0.5https://wasp-lang.dev/blog/tags/clean-codeweekly0.5https://wasp-lang.dev/blog/tags/cssweekly0.5https://wasp-lang.dev/blog/tags/databaseweekly0.5https://wasp-lang.dev/blog/tags/discordweekly0.5https://wasp-lang.dev/blog/tags/expressweekly0.5https://wasp-lang.dev/blog/tags/featureweekly0.5https://wasp-lang.dev/blog/tags/frameworkweekly0.5https://wasp-lang.dev/blog/tags/full-stackweekly0.5https://wasp-lang.dev/blog/tags/fullstackweekly0.5https://wasp-lang.dev/blog/tags/function-callingweekly0.5https://wasp-lang.dev/blog/tags/generateweekly0.5https://wasp-lang.dev/blog/tags/githubweekly0.5https://wasp-lang.dev/blog/tags/gitpodweekly0.5https://wasp-lang.dev/blog/tags/gptweekly0.5https://wasp-lang.dev/blog/tags/hackweekly0.5https://wasp-lang.dev/blog/tags/hackathonweekly0.5https://wasp-lang.dev/blog/tags/hacktoberfestweekly0.5https://wasp-lang.dev/blog/tags/haskellweekly0.5https://wasp-lang.dev/blog/tags/hiringweekly0.5https://wasp-lang.dev/blog/tags/indie-hackerweekly0.5https://wasp-lang.dev/blog/tags/interviewweekly0.5https://wasp-lang.dev/blog/tags/javascriptweekly0.5https://wasp-lang.dev/blog/tags/jobweekly0.5https://wasp-lang.dev/blog/tags/jobsweekly0.5https://wasp-lang.dev/blog/tags/junior-developersweekly0.5https://wasp-lang.dev/blog/tags/langchainweekly0.5https://wasp-lang.dev/blog/tags/languageweekly0.5https://wasp-lang.dev/blog/tags/laravelweekly0.5https://wasp-lang.dev/blog/tags/launch-weekweekly0.5https://wasp-lang.dev/blog/tags/mageweekly0.5https://wasp-lang.dev/blog/tags/marketingweekly0.5https://wasp-lang.dev/blog/tags/memeweekly0.5https://wasp-lang.dev/blog/tags/mlweekly0.5https://wasp-lang.dev/blog/tags/new-hireweekly0.5https://wasp-lang.dev/blog/tags/nodeweekly0.5https://wasp-lang.dev/blog/tags/nodejsweekly0.5https://wasp-lang.dev/blog/tags/open-sourceweekly0.5https://wasp-lang.dev/blog/tags/openaiweekly0.5https://wasp-lang.dev/blog/tags/optimisticweekly0.5https://wasp-lang.dev/blog/tags/pernweekly0.5https://wasp-lang.dev/blog/tags/prdweekly0.5https://wasp-lang.dev/blog/tags/prismaweekly0.5https://wasp-lang.dev/blog/tags/product-requirementweekly0.5https://wasp-lang.dev/blog/tags/product-updateweekly0.5https://wasp-lang.dev/blog/tags/programmingweekly0.5https://wasp-lang.dev/blog/tags/railsweekly0.5https://wasp-lang.dev/blog/tags/reactweekly0.5https://wasp-lang.dev/blog/tags/real-timeweekly0.5https://wasp-lang.dev/blog/tags/redditweekly0.5https://wasp-lang.dev/blog/tags/saa-sweekly0.5https://wasp-lang.dev/blog/tags/saasweekly0.5https://wasp-lang.dev/blog/tags/showcaseweekly0.5https://wasp-lang.dev/blog/tags/solopreneurweekly0.5https://wasp-lang.dev/blog/tags/startupweekly0.5https://wasp-lang.dev/blog/tags/startupsweekly0.5https://wasp-lang.dev/blog/tags/state-of-jsweekly0.5https://wasp-lang.dev/blog/tags/stripeweekly0.5https://wasp-lang.dev/blog/tags/supabaseweekly0.5https://wasp-lang.dev/blog/tags/techweekly0.5https://wasp-lang.dev/blog/tags/tech-careerweekly0.5https://wasp-lang.dev/blog/tags/tutorialweekly0.5https://wasp-lang.dev/blog/tags/typescriptweekly0.5https://wasp-lang.dev/blog/tags/updateweekly0.5https://wasp-lang.dev/blog/tags/updatesweekly0.5https://wasp-lang.dev/blog/tags/waspweekly0.5https://wasp-lang.dev/blog/tags/wasp-aiweekly0.5https://wasp-lang.dev/blog/tags/web-devweekly0.5https://wasp-lang.dev/blog/tags/web-developmentweekly0.5https://wasp-lang.dev/blog/tags/webdevweekly0.5https://wasp-lang.dev/blog/tags/websocketsweekly0.5https://wasp-lang.dev/blog/tags/windowsweekly0.5https://wasp-lang.dev/blog/tags/wslweekly0.5https://wasp-lang.dev/searchweekly0.5https://wasp-lang.dev/docs/0.11.8weekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/apisweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/deployment/cliweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/deployment/manuallyweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/deployment/overviewweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/emailweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/jobsweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/linksweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/middleware-configweekly0.5https://wasp-lang.dev/docs/0.11.8/advanced/web-socketsweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/emailweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/overviewweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/social-auth/githubweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/social-auth/googleweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/social-auth/overviewweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/uiweekly0.5https://wasp-lang.dev/docs/0.11.8/auth/username-and-passweekly0.5https://wasp-lang.dev/docs/0.11.8/contactweekly0.5https://wasp-lang.dev/docs/0.11.8/contributingweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/backendsweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/crudweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/entitiesweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/operations/actionsweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/operations/overviewweekly0.5https://wasp-lang.dev/docs/0.11.8/data-model/operations/queriesweekly0.5https://wasp-lang.dev/docs/0.11.8/editor-setupweekly0.5https://wasp-lang.dev/docs/0.11.8/general/cliweekly0.5https://wasp-lang.dev/docs/0.11.8/general/languageweekly0.5https://wasp-lang.dev/docs/0.11.8/project/client-configweekly0.5https://wasp-lang.dev/docs/0.11.8/project/css-frameworksweekly0.5https://wasp-lang.dev/docs/0.11.8/project/custom-vite-configweekly0.5https://wasp-lang.dev/docs/0.11.8/project/customizing-appweekly0.5https://wasp-lang.dev/docs/0.11.8/project/dependenciesweekly0.5https://wasp-lang.dev/docs/0.11.8/project/env-varsweekly0.5https://wasp-lang.dev/docs/0.11.8/project/server-configweekly0.5https://wasp-lang.dev/docs/0.11.8/project/starter-templatesweekly0.5https://wasp-lang.dev/docs/0.11.8/project/static-assetsweekly0.5https://wasp-lang.dev/docs/0.11.8/project/testingweekly0.5https://wasp-lang.dev/docs/0.11.8/quick-startweekly0.5https://wasp-lang.dev/docs/0.11.8/telemetryweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/actionsweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/authweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/createweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/entitiesweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/pagesweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/project-structureweekly0.5https://wasp-lang.dev/docs/0.11.8/tutorial/queriesweekly0.5https://wasp-lang.dev/docs/0.11.8/visionweekly0.5https://wasp-lang.dev/docs/0.11.8/writingguideweekly0.5https://wasp-lang.dev/docs/0.12.0weekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/apisweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/deployment/cliweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/deployment/manuallyweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/deployment/overviewweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/emailweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/jobsweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/linksweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/middleware-configweekly0.5https://wasp-lang.dev/docs/0.12.0/advanced/web-socketsweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/emailweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/entitiesweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/overviewweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/social-auth/githubweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/social-auth/googleweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/social-auth/overviewweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/uiweekly0.5https://wasp-lang.dev/docs/0.12.0/auth/username-and-passweekly0.5https://wasp-lang.dev/docs/0.12.0/contactweekly0.5https://wasp-lang.dev/docs/0.12.0/contributingweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/backendsweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/crudweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/entitiesweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/operations/actionsweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/operations/overviewweekly0.5https://wasp-lang.dev/docs/0.12.0/data-model/operations/queriesweekly0.5https://wasp-lang.dev/docs/0.12.0/editor-setupweekly0.5https://wasp-lang.dev/docs/0.12.0/general/cliweekly0.5https://wasp-lang.dev/docs/0.12.0/general/languageweekly0.5https://wasp-lang.dev/docs/0.12.0/migrate-from-0-11-to-0-12weekly0.5https://wasp-lang.dev/docs/0.12.0/project/client-configweekly0.5https://wasp-lang.dev/docs/0.12.0/project/css-frameworksweekly0.5https://wasp-lang.dev/docs/0.12.0/project/custom-vite-configweekly0.5https://wasp-lang.dev/docs/0.12.0/project/customizing-appweekly0.5https://wasp-lang.dev/docs/0.12.0/project/dependenciesweekly0.5https://wasp-lang.dev/docs/0.12.0/project/env-varsweekly0.5https://wasp-lang.dev/docs/0.12.0/project/server-configweekly0.5https://wasp-lang.dev/docs/0.12.0/project/starter-templatesweekly0.5https://wasp-lang.dev/docs/0.12.0/project/static-assetsweekly0.5https://wasp-lang.dev/docs/0.12.0/project/testingweekly0.5https://wasp-lang.dev/docs/0.12.0/quick-startweekly0.5https://wasp-lang.dev/docs/0.12.0/telemetryweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/actionsweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/authweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/createweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/entitiesweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/pagesweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/project-structureweekly0.5https://wasp-lang.dev/docs/0.12.0/tutorial/queriesweekly0.5https://wasp-lang.dev/docs/0.12.0/visionweekly0.5https://wasp-lang.dev/docs/0.12.0/wasp-ai/creating-new-appweekly0.5https://wasp-lang.dev/docs/0.12.0/wasp-ai/developing-existing-appweekly0.5https://wasp-lang.dev/docs/0.12.0/writingguideweekly0.5https://wasp-lang.dev/docsweekly0.5https://wasp-lang.dev/docs/advanced/accessing-app-configweekly0.5https://wasp-lang.dev/docs/advanced/apisweekly0.5https://wasp-lang.dev/docs/advanced/deployment/cliweekly0.5https://wasp-lang.dev/docs/advanced/deployment/manuallyweekly0.5https://wasp-lang.dev/docs/advanced/deployment/overviewweekly0.5https://wasp-lang.dev/docs/advanced/emailweekly0.5https://wasp-lang.dev/docs/advanced/jobsweekly0.5https://wasp-lang.dev/docs/advanced/linksweekly0.5https://wasp-lang.dev/docs/advanced/middleware-configweekly0.5https://wasp-lang.dev/docs/advanced/web-socketsweekly0.5https://wasp-lang.dev/docs/auth/emailweekly0.5https://wasp-lang.dev/docs/auth/entitiesweekly0.5https://wasp-lang.dev/docs/auth/overviewweekly0.5https://wasp-lang.dev/docs/auth/social-auth/githubweekly0.5https://wasp-lang.dev/docs/auth/social-auth/googleweekly0.5https://wasp-lang.dev/docs/auth/social-auth/keycloakweekly0.5https://wasp-lang.dev/docs/auth/social-auth/overviewweekly0.5https://wasp-lang.dev/docs/auth/uiweekly0.5https://wasp-lang.dev/docs/auth/username-and-passweekly0.5https://wasp-lang.dev/docs/contactweekly0.5https://wasp-lang.dev/docs/contributingweekly0.5https://wasp-lang.dev/docs/data-model/backendsweekly0.5https://wasp-lang.dev/docs/data-model/crudweekly0.5https://wasp-lang.dev/docs/data-model/entitiesweekly0.5https://wasp-lang.dev/docs/data-model/operations/actionsweekly0.5https://wasp-lang.dev/docs/data-model/operations/overviewweekly0.5https://wasp-lang.dev/docs/data-model/operations/queriesweekly0.5https://wasp-lang.dev/docs/editor-setupweekly0.5https://wasp-lang.dev/docs/general/cliweekly0.5https://wasp-lang.dev/docs/general/languageweekly0.5https://wasp-lang.dev/docs/migrate-from-0-11-to-0-12weekly0.5https://wasp-lang.dev/docs/migrate-from-0-12-to-0-13weekly0.5https://wasp-lang.dev/docs/project/client-configweekly0.5https://wasp-lang.dev/docs/project/css-frameworksweekly0.5https://wasp-lang.dev/docs/project/custom-vite-configweekly0.5https://wasp-lang.dev/docs/project/customizing-appweekly0.5https://wasp-lang.dev/docs/project/dependenciesweekly0.5https://wasp-lang.dev/docs/project/env-varsweekly0.5https://wasp-lang.dev/docs/project/server-configweekly0.5https://wasp-lang.dev/docs/project/starter-templatesweekly0.5https://wasp-lang.dev/docs/project/static-assetsweekly0.5https://wasp-lang.dev/docs/project/testingweekly0.5https://wasp-lang.dev/docs/quick-startweekly0.5https://wasp-lang.dev/docs/telemetryweekly0.5https://wasp-lang.dev/docs/tutorial/actionsweekly0.5https://wasp-lang.dev/docs/tutorial/authweekly0.5https://wasp-lang.dev/docs/tutorial/createweekly0.5https://wasp-lang.dev/docs/tutorial/entitiesweekly0.5https://wasp-lang.dev/docs/tutorial/pagesweekly0.5https://wasp-lang.dev/docs/tutorial/project-structureweekly0.5https://wasp-lang.dev/docs/tutorial/queriesweekly0.5https://wasp-lang.dev/docs/visionweekly0.5https://wasp-lang.dev/docs/wasp-ai/creating-new-appweekly0.5https://wasp-lang.dev/docs/wasp-ai/developing-existing-appweekly0.5https://wasp-lang.dev/docs/writingguideweekly0.5https://wasp-lang.dev/weekly0.5
\ No newline at end of file