diff --git a/404.html b/404.html index ee686bb029..b54b9bdebb 100644 --- a/404.html +++ b/404.html @@ -18,14 +18,14 @@ - - - + + +
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/css/styles.5d60d09a.css b/assets/css/styles.5d60d09a.css new file mode 100644 index 0000000000..6260b64aa2 --- /dev/null +++ b/assets/css/styles.5d60d09a.css @@ -0,0 +1 @@ +@import url(https://fonts.googleapis.com/css2?family=Inter:wght@100;200;300;400;500;600;700;800;900&display=swap);.col,.container{padding:0 var(--ifm-spacing-horizontal)}.markdown>h2,.markdown>h3,.markdown>h4,.markdown>h5,.markdown>h6{margin-bottom:calc(var(--ifm-heading-vertical-rhythm-bottom)*var(--ifm-leading))}blockquote,pre{margin:0 0 var(--ifm-spacing-vertical)}.breadcrumbs__link,.button{transition-timing-function:var(--ifm-transition-timing-default)}.button,code{vertical-align:middle}.button--outline.button--active,.button--outline:active,.button--outline:hover,:root{--ifm-button-color:var(--ifm-font-color-base-inverse)}.menu__link:hover,a{transition:color var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.navbar--dark,:root{--ifm-navbar-link-hover-color:var(--ifm-color-primary)}.menu,.navbar-sidebar{overflow-x:hidden}:root,html[data-theme=dark]{--ifm-color-emphasis-500:var(--ifm-color-gray-500)}.border-blue-500,.border-fuchsia-600,.border-green-600,.border-neutral-300,.border-neutral-500,.border-yellow-600,.hover\:border-neutral-400:hover,.hover\:border-yellow-400:hover{--tw-border-opacity:1!important}.bg-\[\#F3EDE0\],.bg-\[\#f5f4f0\],.bg-\[\#f5f5f5\],.bg-fuchsia-50,.bg-gray-200,.bg-green-50,.bg-neutral-500,.bg-neutral-700,.bg-slate-50,.bg-white,.bg-yellow-50,.bg-yellow-500,.hover\:bg-gray-100:hover,.hover\:bg-gray-50:hover,.hover\:bg-neutral-200:hover,.hover\:bg-yellow-400:hover{--tw-bg-opacity:1!important}.hover\:text-neutral-400:hover,.hover\:text-neutral-500:hover,.text-blue-500,.text-fuchsia-600,.text-green-600,.text-neutral-400,.text-neutral-500,.text-neutral-600,.text-neutral-700,.text-neutral-800,.text-white,.text-yellow-400,.text-yellow-600{--tw-text-opacity:1!important}pre,table{overflow:auto}.toggleButton_gllP,html{-webkit-tap-highlight-color:transparent}.markdown li,body{word-wrap:break-word}*,.DocSearch-Container,.DocSearch-Container *,:after,:before{box-sizing:border-box}:root{--ifm-color-scheme:light;--ifm-dark-value:10%;--ifm-darker-value:15%;--ifm-darkest-value:30%;--ifm-light-value:15%;--ifm-lighter-value:30%;--ifm-lightest-value:50%;--ifm-contrast-background-value:90%;--ifm-contrast-foreground-value:70%;--ifm-contrast-background-dark-value:70%;--ifm-contrast-foreground-dark-value:90%;--ifm-color-primary:#3578e5;--ifm-color-secondary:#ebedf0;--ifm-color-success:#00a400;--ifm-color-info:#54c7ec;--ifm-color-warning:#ffba00;--ifm-color-danger:#fa383e;--ifm-color-primary-dark:#306cce;--ifm-color-primary-darker:#2d66c3;--ifm-color-primary-darkest:#2554a0;--ifm-color-primary-light:#538ce9;--ifm-color-primary-lighter:#72a1ed;--ifm-color-primary-lightest:#9abcf2;--ifm-color-primary-contrast-background:#ebf2fc;--ifm-color-primary-contrast-foreground:#102445;--ifm-color-secondary-dark:#d4d5d8;--ifm-color-secondary-darker:#c8c9cc;--ifm-color-secondary-darkest:#a4a6a8;--ifm-color-secondary-light:#eef0f2;--ifm-color-secondary-lighter:#f1f2f5;--ifm-color-secondary-lightest:#f5f6f8;--ifm-color-secondary-contrast-background:#fdfdfe;--ifm-color-secondary-contrast-foreground:#474748;--ifm-color-success-dark:#009400;--ifm-color-success-darker:#008b00;--ifm-color-success-darkest:#007300;--ifm-color-success-light:#26b226;--ifm-color-success-lighter:#4dbf4d;--ifm-color-success-lightest:#80d280;--ifm-color-success-contrast-background:#e6f6e6;--ifm-color-success-contrast-foreground:#003100;--ifm-color-info-dark:#4cb3d4;--ifm-color-info-darker:#47a9c9;--ifm-color-info-darkest:#3b8ba5;--ifm-color-info-light:#6ecfef;--ifm-color-info-lighter:#87d8f2;--ifm-color-info-lightest:#aae3f6;--ifm-color-info-contrast-background:#eef9fd;--ifm-color-info-contrast-foreground:#193c47;--ifm-color-warning-dark:#e6a700;--ifm-color-warning-darker:#d99e00;--ifm-color-warning-darkest:#b38200;--ifm-color-warning-light:#ffc426;--ifm-color-warning-lighter:#ffcf4d;--ifm-color-warning-lightest:#ffdd80;--ifm-color-warning-contrast-background:#fff8e6;--ifm-color-warning-contrast-foreground:#4d3800;--ifm-color-danger-dark:#e13238;--ifm-color-danger-darker:#d53035;--ifm-color-danger-darkest:#af272b;--ifm-color-danger-light:#fb565b;--ifm-color-danger-lighter:#fb7478;--ifm-color-danger-lightest:#fd9c9f;--ifm-color-danger-contrast-background:#ffebec;--ifm-color-danger-contrast-foreground:#4b1113;--ifm-color-white:#fff;--ifm-color-black:#000;--ifm-color-gray-0:var(--ifm-color-white);--ifm-color-gray-100:#f5f6f7;--ifm-color-gray-200:#ebedf0;--ifm-color-gray-300:#dadde1;--ifm-color-gray-400:#ccd0d5;--ifm-color-gray-500:#bec3c9;--ifm-color-gray-600:#8d949e;--ifm-color-gray-700:#606770;--ifm-color-gray-800:#444950;--ifm-color-gray-900:#1c1e21;--ifm-color-gray-1000:var(--ifm-color-black);--ifm-color-emphasis-0:var(--ifm-color-gray-0);--ifm-color-emphasis-100:var(--ifm-color-gray-100);--ifm-color-emphasis-200:var(--ifm-color-gray-200);--ifm-color-emphasis-300:var(--ifm-color-gray-300);--ifm-color-emphasis-400:var(--ifm-color-gray-400);--ifm-color-emphasis-600:var(--ifm-color-gray-600);--ifm-color-emphasis-700:var(--ifm-color-gray-700);--ifm-color-emphasis-800:var(--ifm-color-gray-800);--ifm-color-emphasis-900:var(--ifm-color-gray-900);--ifm-color-emphasis-1000:var(--ifm-color-gray-1000);--ifm-color-content:var(--ifm-color-emphasis-900);--ifm-color-content-inverse:var(--ifm-color-emphasis-0);--ifm-color-content-secondary:#525860;--ifm-background-color:#0000;--ifm-background-surface-color:var(--ifm-color-content-inverse);--ifm-global-border-width:1px;--ifm-global-radius:0.4rem;--ifm-hover-overlay:#0000000d;--ifm-font-color-base:var(--ifm-color-content);--ifm-font-color-base-inverse:var(--ifm-color-content-inverse);--ifm-font-color-secondary:var(--ifm-color-content-secondary);--ifm-font-family-base:system-ui,-apple-system,Segoe UI,Roboto,Ubuntu,Cantarell,Noto Sans,sans-serif,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";--ifm-font-family-monospace:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;--ifm-font-size-base:100%;--ifm-font-weight-light:300;--ifm-font-weight-normal:400;--ifm-font-weight-semibold:500;--ifm-font-weight-bold:700;--ifm-font-weight-base:var(--ifm-font-weight-normal);--ifm-line-height-base:1.65;--ifm-global-spacing:1rem;--ifm-spacing-vertical:var(--ifm-global-spacing);--ifm-spacing-horizontal:var(--ifm-global-spacing);--ifm-transition-fast:200ms;--ifm-transition-slow:400ms;--ifm-transition-timing-default:cubic-bezier(0.08,0.52,0.52,1);--ifm-global-shadow-lw:0 1px 2px 0 #0000001a;--ifm-global-shadow-md:0 5px 40px #0003;--ifm-global-shadow-tl:0 12px 28px 0 #0003,0 2px 4px 0 #0000001a;--ifm-z-index-dropdown:100;--ifm-z-index-fixed:200;--ifm-z-index-overlay:400;--ifm-container-width:1140px;--ifm-container-width-xl:1320px;--ifm-code-background:#f6f7f8;--ifm-code-border-radius:var(--ifm-global-radius);--ifm-code-font-size:90%;--ifm-code-padding-horizontal:0.1rem;--ifm-code-padding-vertical:0.1rem;--ifm-pre-background:var(--ifm-code-background);--ifm-pre-border-radius:var(--ifm-code-border-radius);--ifm-pre-color:inherit;--ifm-pre-line-height:1.45;--ifm-pre-padding:1rem;--ifm-heading-color:inherit;--ifm-heading-margin-top:0;--ifm-heading-margin-bottom:var(--ifm-spacing-vertical);--ifm-heading-font-family:var(--ifm-font-family-base);--ifm-heading-font-weight:var(--ifm-font-weight-bold);--ifm-heading-line-height:1.25;--ifm-h1-font-size:2rem;--ifm-h2-font-size:1.5rem;--ifm-h3-font-size:1.25rem;--ifm-h4-font-size:1rem;--ifm-h5-font-size:0.875rem;--ifm-h6-font-size:0.85rem;--ifm-image-alignment-padding:1.25rem;--ifm-leading-desktop:1.25;--ifm-leading:calc(var(--ifm-leading-desktop)*1rem);--ifm-list-left-padding:2rem;--ifm-list-margin:1rem;--ifm-list-item-margin:0.25rem;--ifm-list-paragraph-margin:1rem;--ifm-table-cell-padding:0.75rem;--ifm-table-background:#0000;--ifm-table-stripe-background:#00000008;--ifm-table-border-width:1px;--ifm-table-border-color:var(--ifm-color-emphasis-300);--ifm-table-head-background:inherit;--ifm-table-head-color:inherit;--ifm-table-head-font-weight:var(--ifm-font-weight-bold);--ifm-table-cell-color:inherit;--ifm-link-color:var(--ifm-color-primary);--ifm-link-decoration:none;--ifm-link-hover-color:var(--ifm-link-color);--ifm-link-hover-decoration:underline;--ifm-paragraph-margin-bottom:var(--ifm-leading);--ifm-blockquote-font-size:var(--ifm-font-size-base);--ifm-blockquote-border-left-width:2px;--ifm-blockquote-padding-horizontal:var(--ifm-spacing-horizontal);--ifm-blockquote-padding-vertical:0;--ifm-blockquote-shadow:none;--ifm-blockquote-color:var(--ifm-color-emphasis-800);--ifm-blockquote-border-color:var(--ifm-color-emphasis-300);--ifm-hr-background-color:var(--ifm-color-emphasis-500);--ifm-hr-height:1px;--ifm-hr-margin-vertical:1.5rem;--ifm-scrollbar-size:7px;--ifm-scrollbar-track-background-color:#f1f1f1;--ifm-scrollbar-thumb-background-color:silver;--ifm-scrollbar-thumb-hover-background-color:#a7a7a7;--ifm-alert-background-color:inherit;--ifm-alert-border-color:inherit;--ifm-alert-border-radius:var(--ifm-global-radius);--ifm-alert-border-width:0px;--ifm-alert-border-left-width:5px;--ifm-alert-color:var(--ifm-font-color-base);--ifm-alert-padding-horizontal:var(--ifm-spacing-horizontal);--ifm-alert-padding-vertical:var(--ifm-spacing-vertical);--ifm-alert-shadow:var(--ifm-global-shadow-lw);--ifm-avatar-intro-margin:1rem;--ifm-avatar-intro-alignment:inherit;--ifm-avatar-photo-size:3rem;--ifm-badge-background-color:inherit;--ifm-badge-border-color:inherit;--ifm-badge-border-radius:var(--ifm-global-radius);--ifm-badge-border-width:var(--ifm-global-border-width);--ifm-badge-color:var(--ifm-color-white);--ifm-badge-padding-horizontal:calc(var(--ifm-spacing-horizontal)*0.5);--ifm-badge-padding-vertical:calc(var(--ifm-spacing-vertical)*0.25);--ifm-breadcrumb-border-radius:1.5rem;--ifm-breadcrumb-spacing:0.5rem;--ifm-breadcrumb-color-active:var(--ifm-color-primary);--ifm-breadcrumb-item-background-active:var(--ifm-hover-overlay);--ifm-breadcrumb-padding-horizontal:0.8rem;--ifm-breadcrumb-padding-vertical:0.4rem;--ifm-breadcrumb-size-multiplier:1;--ifm-breadcrumb-separator:url('data:image/svg+xml;utf8,');--ifm-breadcrumb-separator-filter:none;--ifm-breadcrumb-separator-size:0.5rem;--ifm-breadcrumb-separator-size-multiplier:1.25;--ifm-button-background-color:inherit;--ifm-button-border-color:var(--ifm-button-background-color);--ifm-button-border-width:var(--ifm-global-border-width);--ifm-button-font-weight:var(--ifm-font-weight-bold);--ifm-button-padding-horizontal:1.5rem;--ifm-button-padding-vertical:0.375rem;--ifm-button-size-multiplier:1;--ifm-button-transition-duration:var(--ifm-transition-fast);--ifm-button-border-radius:calc(var(--ifm-global-radius)*var(--ifm-button-size-multiplier));--ifm-button-group-spacing:2px;--ifm-card-background-color:var(--ifm-background-surface-color);--ifm-card-border-radius:calc(var(--ifm-global-radius)*2);--ifm-card-horizontal-spacing:var(--ifm-global-spacing);--ifm-card-vertical-spacing:var(--ifm-global-spacing);--ifm-toc-border-color:var(--ifm-color-emphasis-300);--ifm-toc-link-color:var(--ifm-color-content-secondary);--ifm-toc-padding-vertical:0.5rem;--ifm-toc-padding-horizontal:0.5rem;--ifm-dropdown-background-color:var(--ifm-background-surface-color);--ifm-dropdown-font-weight:var(--ifm-font-weight-semibold);--ifm-dropdown-link-color:var(--ifm-font-color-base);--ifm-dropdown-hover-background-color:var(--ifm-hover-overlay);--ifm-footer-background-color:var(--ifm-color-emphasis-100);--ifm-footer-color:inherit;--ifm-footer-link-color:var(--ifm-color-emphasis-700);--ifm-footer-link-hover-color:var(--ifm-color-primary);--ifm-footer-link-horizontal-spacing:0.5rem;--ifm-footer-padding-horizontal:calc(var(--ifm-spacing-horizontal)*2);--ifm-footer-padding-vertical:calc(var(--ifm-spacing-vertical)*2);--ifm-footer-title-color:inherit;--ifm-footer-logo-max-width:min(30rem,90vw);--ifm-hero-background-color:var(--ifm-background-surface-color);--ifm-hero-text-color:var(--ifm-color-emphasis-800);--ifm-menu-color:var(--ifm-color-emphasis-700);--ifm-menu-color-active:var(--ifm-color-primary);--ifm-menu-color-background-active:var(--ifm-hover-overlay);--ifm-menu-color-background-hover:var(--ifm-hover-overlay);--ifm-menu-link-padding-horizontal:0.75rem;--ifm-menu-link-padding-vertical:0.375rem;--ifm-menu-link-sublist-icon:url('data:image/svg+xml;utf8,');--ifm-menu-link-sublist-icon-filter:none;--ifm-navbar-background-color:var(--ifm-background-surface-color);--ifm-navbar-height:3.75rem;--ifm-navbar-item-padding-horizontal:0.75rem;--ifm-navbar-item-padding-vertical:0.25rem;--ifm-navbar-link-color:var(--ifm-font-color-base);--ifm-navbar-link-active-color:var(--ifm-link-color);--ifm-navbar-padding-horizontal:var(--ifm-spacing-horizontal);--ifm-navbar-padding-vertical:calc(var(--ifm-spacing-vertical)*0.5);--ifm-navbar-shadow:var(--ifm-global-shadow-lw);--ifm-navbar-search-input-background-color:var(--ifm-color-emphasis-200);--ifm-navbar-search-input-color:var(--ifm-color-emphasis-800);--ifm-navbar-search-input-placeholder-color:var(--ifm-color-emphasis-500);--ifm-navbar-search-input-icon:url('data:image/svg+xml;utf8,');--ifm-navbar-sidebar-width:83vw;--ifm-pagination-border-radius:var(--ifm-global-radius);--ifm-pagination-color-active:var(--ifm-color-primary);--ifm-pagination-font-size:1rem;--ifm-pagination-item-active-background:var(--ifm-hover-overlay);--ifm-pagination-page-spacing:0.2em;--ifm-pagination-padding-horizontal:calc(var(--ifm-spacing-horizontal)*1);--ifm-pagination-padding-vertical:calc(var(--ifm-spacing-vertical)*0.25);--ifm-pagination-nav-border-radius:var(--ifm-global-radius);--ifm-pagination-nav-color-hover:var(--ifm-color-primary);--ifm-pills-color-active:var(--ifm-color-primary);--ifm-pills-color-background-active:var(--ifm-hover-overlay);--ifm-pills-spacing:0.125rem;--ifm-tabs-color:var(--ifm-font-color-secondary);--ifm-tabs-color-active:var(--ifm-color-primary);--ifm-tabs-color-active-border:var(--ifm-tabs-color-active);--ifm-tabs-padding-horizontal:1rem;--ifm-tabs-padding-vertical:1rem}.markdown>h2,:root{--ifm-h2-font-size:2rem}.badge--danger,.badge--info,.badge--primary,.badge--secondary,.badge--success,.badge--warning{--ifm-badge-border-color:var(--ifm-badge-background-color)}.button--link,.button--outline{--ifm-button-background-color:#0000}html{-webkit-font-smoothing:antialiased;text-size-adjust:100%;background-color:var(--ifm-background-color);color:var(--ifm-font-color-base);color-scheme:var(--ifm-color-scheme);font:var(--ifm-font-size-base)/var(--ifm-line-height-base) var(--ifm-font-family-base);text-rendering:optimizelegibility}iframe{border:0;color-scheme:auto}.container{margin:0 auto;max-width:var(--ifm-container-width)}.container--fluid{max-width:inherit}.row{display:flex;flex-wrap:wrap;margin:0 calc(var(--ifm-spacing-horizontal)*-1)}.margin-bottom--none,.margin-vert--none,.markdown>:last-child,.mb-0{margin-bottom:0!important}.margin-top--none,.margin-vert--none,.mt-0,.tabItem_LNqP{margin-top:0!important}.row--no-gutters{margin-left:0;margin-right:0}.margin-horiz--none,.margin-right--none{margin-right:0!important}.row--no-gutters>.col{padding-left:0;padding-right:0}.row--align-top{align-items:flex-start}.row--align-bottom{align-items:flex-end}.menuExternalLink_NmtK,.row--align-center{align-items:center}.row--align-stretch{align-items:stretch}.row--align-baseline{align-items:baseline}.col{--ifm-col-width:100%;flex:1 0;margin-left:0;max-width:var(--ifm-col-width);width:100%}.padding-bottom--none,.padding-vert--none,.py-0{padding-bottom:0!important}.padding-horiz--none,.padding-left--none{padding-left:0!important}.padding-horiz--none,.padding-right--none{padding-right:0!important}.col[class*=col--]{flex:0 0 var(--ifm-col-width)}.col--1{--ifm-col-width:8.33333%}.col--offset-1{margin-left:8.33333%}.col--2{--ifm-col-width:16.66667%}.col--offset-2{margin-left:16.66667%}.col--3{--ifm-col-width:25%}.col--offset-3{margin-left:25%}.col--4{--ifm-col-width:33.33333%}.col--offset-4{margin-left:33.33333%}.col--5{--ifm-col-width:41.66667%}.col--offset-5{margin-left:41.66667%}.col--6{--ifm-col-width:50%}.col--offset-6{margin-left:50%}.col--7{--ifm-col-width:58.33333%}.col--offset-7{margin-left:58.33333%}.col--8{--ifm-col-width:66.66667%}.col--offset-8{margin-left:66.66667%}.col--9{--ifm-col-width:75%}.col--offset-9{margin-left:75%}.col--10{--ifm-col-width:83.33333%}.col--offset-10{margin-left:83.33333%}.col--11{--ifm-col-width:91.66667%}.col--offset-11{margin-left:91.66667%}.col--12{--ifm-col-width:100%}.col--offset-12{margin-left:100%}.group:hover .group-hover\:ml-0,.margin-horiz--none,.margin-left--none{margin-left:0!important}.margin--none{margin:0!important}.margin-bottom--xs,.margin-vert--xs{margin-bottom:.25rem!important}.margin-top--xs,.margin-vert--xs{margin-top:.25rem!important}.margin-horiz--xs,.margin-left--xs,.ml-1{margin-left:.25rem!important}.margin-horiz--xs,.margin-right--xs{margin-right:.25rem!important}.margin--xs{margin:.25rem!important}.margin-bottom--sm,.margin-vert--sm{margin-bottom:.5rem!important}.margin-top--sm,.margin-vert--sm,.mt-2{margin-top:.5rem!important}.margin-horiz--sm,.margin-left--sm,.ml-2,.mx-2{margin-left:.5rem!important}.margin-horiz--sm,.margin-right--sm,.mx-2{margin-right:.5rem!important}.margin--sm{margin:.5rem!important}.margin-bottom--md,.margin-vert--md,.mb-4,.my-4{margin-bottom:1rem!important}.margin-top--md,.margin-vert--md,.mt-4,.my-4{margin-top:1rem!important}.margin-horiz--md,.margin-left--md,.ml-4{margin-left:1rem!important}.margin-horiz--md,.margin-right--md{margin-right:1rem!important}.margin--md{margin:1rem!important}.margin-bottom--lg,.margin-vert--lg,.mb-8{margin-bottom:2rem!important}.margin-top--lg,.margin-vert--lg,.mt-8{margin-top:2rem!important}.margin-horiz--lg,.margin-left--lg{margin-left:2rem!important}.margin-horiz--lg,.margin-right--lg{margin-right:2rem!important}.margin--lg{margin:2rem!important}.margin-bottom--xl,.margin-vert--xl{margin-bottom:5rem!important}.margin-top--xl,.margin-vert--xl,.mt-20{margin-top:5rem!important}.margin-horiz--xl,.margin-left--xl{margin-left:5rem!important}.margin-horiz--xl,.margin-right--xl{margin-right:5rem!important}.margin--xl{margin:5rem!important}.padding--none{padding:0!important}.padding-top--none{padding-top:0!important}.padding-vert--none,.py-0{padding-top:0!important}.padding-bottom--xs,.padding-vert--xs,.py-1{padding-bottom:.25rem!important}.padding-top--xs,.padding-vert--xs,.py-1{padding-top:.25rem!important}.padding-horiz--xs,.padding-left--xs,.px-1{padding-left:.25rem!important}.padding-horiz--xs,.padding-right--xs,.px-1{padding-right:.25rem!important}.padding--xs{padding:.25rem!important}.padding-bottom--sm,.padding-vert--sm,.py-2{padding-bottom:.5rem!important}.padding-top--sm,.padding-vert--sm,.pt-2,.py-2{padding-top:.5rem!important}.padding-horiz--sm,.padding-left--sm,.px-2{padding-left:.5rem!important}.padding-horiz--sm,.padding-right--sm,.px-2{padding-right:.5rem!important}.p-2,.padding--sm{padding:.5rem!important}.padding-bottom--md,.padding-vert--md,.pb-4{padding-bottom:1rem!important}.padding-top--md,.padding-vert--md{padding-top:1rem!important}.padding-horiz--md,.padding-left--md,.pl-4,.px-4{padding-left:1rem!important}.padding-horiz--md,.padding-right--md,.pr-4,.px-4{padding-right:1rem!important}.p-4,.padding--md{padding:1rem!important}.padding-bottom--lg,.padding-vert--lg,.pb-8,.py-8{padding-bottom:2rem!important}.padding-top--lg,.padding-vert--lg,.pt-8,.py-8{padding-top:2rem!important}.padding-horiz--lg,.padding-left--lg{padding-left:2rem!important}.padding-horiz--lg,.padding-right--lg{padding-right:2rem!important}.p-8,.padding--lg{padding:2rem!important}.padding-bottom--xl,.padding-vert--xl,.pb-20,.py-20{padding-bottom:5rem!important}.padding-top--xl,.padding-vert--xl,.py-20{padding-top:5rem!important}.padding-horiz--xl,.padding-left--xl{padding-left:5rem!important}.padding-horiz--xl,.padding-right--xl{padding-right:5rem!important}.padding--xl{padding:5rem!important}code{background-color:var(--ifm-code-background);border:.1rem solid #0000001a;border-radius:var(--ifm-code-border-radius);font-family:var(--ifm-font-family-monospace);font-size:var(--ifm-code-font-size);padding:var(--ifm-code-padding-vertical) var(--ifm-code-padding-horizontal)}a code{color:inherit}pre{background-color:var(--ifm-pre-background);border-radius:var(--ifm-pre-border-radius);color:var(--ifm-pre-color);font:var(--ifm-code-font-size)/var(--ifm-pre-line-height) var(--ifm-font-family-monospace);padding:var(--ifm-pre-padding)}pre code{background-color:initial;border:none;font-size:100%;padding:0}kbd{background-color:var(--ifm-color-emphasis-0);border:1px solid var(--ifm-color-emphasis-400);border-radius:.2rem;box-shadow:inset 0 -1px 0 var(--ifm-color-emphasis-400);color:var(--ifm-color-emphasis-800);font:80% var(--ifm-font-family-monospace);padding:.15rem .3rem}h1,h2,h3,h4,h5,h6{color:var(--ifm-heading-color);font-family:var(--ifm-heading-font-family);font-weight:var(--ifm-heading-font-weight);line-height:var(--ifm-heading-line-height);margin:var(--ifm-heading-margin-top) 0 var(--ifm-heading-margin-bottom) 0}h1{font-size:var(--ifm-h1-font-size)}h2{font-size:var(--ifm-h2-font-size)}h3{font-size:var(--ifm-h3-font-size)}h4{font-size:var(--ifm-h4-font-size)}h5{font-size:var(--ifm-h5-font-size)}h6{font-size:var(--ifm-h6-font-size)}img{max-width:100%}img[align=right]{padding-left:var(--image-alignment-padding)}img[align=left]{padding-right:var(--image-alignment-padding)}.markdown{--ifm-h1-vertical-rhythm-top:3;--ifm-h2-vertical-rhythm-top:2;--ifm-h3-vertical-rhythm-top:1.5;--ifm-heading-vertical-rhythm-top:1.25;--ifm-h1-vertical-rhythm-bottom:1.25;--ifm-heading-vertical-rhythm-bottom:1}.markdown:after,.markdown:before{content:"";display:table}.markdown:after{clear:both}.markdown h1:first-child{--ifm-h1-font-size:3rem;margin-bottom:calc(var(--ifm-h1-vertical-rhythm-bottom)*var(--ifm-leading))}.markdown>h2{margin-top:calc(var(--ifm-h2-vertical-rhythm-top)*var(--ifm-leading))}.markdown>h3{--ifm-h3-font-size:1.5rem;margin-top:calc(var(--ifm-h3-vertical-rhythm-top)*var(--ifm-leading))}.markdown>h4,.markdown>h5,.markdown>h6{margin-top:calc(var(--ifm-heading-vertical-rhythm-top)*var(--ifm-leading))}.markdown>p,.markdown>pre,.markdown>ul,.tabList__CuJ{margin-bottom:var(--ifm-leading)}.markdown li>p{margin-top:var(--ifm-list-paragraph-margin)}.markdown li+li{margin-top:var(--ifm-list-item-margin)}ol,ul{margin:0 0 var(--ifm-list-margin);padding-left:var(--ifm-list-left-padding)}ol ol,ul ol{list-style-type:lower-roman}ol ol,ol ul,ul ol,ul ul{margin:0}ol ol ol,ol ul ol,ul ol ol,ul ul ol{list-style-type:lower-alpha}table{border-collapse:collapse;display:block;margin-bottom:var(--ifm-spacing-vertical)}table thead tr{border-bottom:2px solid var(--ifm-table-border-color)}table thead,table tr:nth-child(2n){background-color:var(--ifm-table-stripe-background)}table tr{background-color:var(--ifm-table-background);border-top:var(--ifm-table-border-width) solid var(--ifm-table-border-color)}table td,table th{border:var(--ifm-table-border-width) solid var(--ifm-table-border-color);padding:var(--ifm-table-cell-padding)}table th{background-color:var(--ifm-table-head-background);color:var(--ifm-table-head-color);font-weight:var(--ifm-table-head-font-weight)}table td{color:var(--ifm-table-cell-color)}strong{font-weight:var(--ifm-font-weight-bold)}a{color:var(--ifm-link-color);text-decoration:var(--ifm-link-decoration)}a:hover{color:var(--ifm-link-hover-color);text-decoration:var(--ifm-link-hover-decoration)}.button:hover,.text--no-decoration,.text--no-decoration:hover,a:not([href]){text-decoration:none}p{margin:0 0 var(--ifm-paragraph-margin-bottom)}blockquote{border-left:var(--ifm-blockquote-border-left-width) solid var(--ifm-blockquote-border-color);box-shadow:var(--ifm-blockquote-shadow);color:var(--ifm-blockquote-color);font-size:var(--ifm-blockquote-font-size);padding:var(--ifm-blockquote-padding-vertical) var(--ifm-blockquote-padding-horizontal)}blockquote>:first-child{margin-top:0}blockquote>:last-child{margin-bottom:0}hr{background-color:var(--ifm-hr-background-color);border:0;height:var(--ifm-hr-height);margin:var(--ifm-hr-margin-vertical) 0}.shadow--lw{box-shadow:var(--ifm-global-shadow-lw)!important}.shadow--md{box-shadow:var(--ifm-global-shadow-md)!important}.shadow--tl{box-shadow:var(--ifm-global-shadow-tl)!important}.text--primary,.wordWrapButtonEnabled_EoeP .wordWrapButtonIcon_Bwma{color:var(--ifm-color-primary)}.text--secondary{color:var(--ifm-color-secondary)}.text--success{color:var(--ifm-color-success)}.text--info{color:var(--ifm-color-info)}.text--warning{color:var(--ifm-color-warning)}.text--danger{color:var(--ifm-color-danger)}.text--center{text-align:center}.text--left{text-align:left}.text--justify{text-align:justify}.text--right{text-align:right}.text--capitalize{text-transform:capitalize}.text--lowercase{text-transform:lowercase}.alert__heading,.text--uppercase{text-transform:uppercase}.text--light{font-weight:var(--ifm-font-weight-light)}.text--normal{font-weight:var(--ifm-font-weight-normal)}.text--semibold{font-weight:var(--ifm-font-weight-semibold)}.text--bold{font-weight:var(--ifm-font-weight-bold)}.text--italic,.token.italic{font-style:italic}.text--truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.text--break{word-wrap:break-word!important;word-break:break-word!important}.clean-btn{background:none;border:none;color:inherit;cursor:pointer;font-family:inherit;padding:0}.alert,.alert .close{color:var(--ifm-alert-foreground-color)}.clean-list{list-style:none;padding-left:0}.alert--primary{--ifm-alert-background-color:var(--ifm-color-primary-contrast-background);--ifm-alert-background-color-highlight:#3578e526;--ifm-alert-foreground-color:var(--ifm-color-primary-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-primary-dark)}.alert--secondary{--ifm-alert-background-color:var(--ifm-color-secondary-contrast-background);--ifm-alert-background-color-highlight:#ebedf026;--ifm-alert-foreground-color:var(--ifm-color-secondary-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-secondary-dark)}.alert--success{--ifm-alert-background-color:var(--ifm-color-success-contrast-background);--ifm-alert-background-color-highlight:#00a40026;--ifm-alert-foreground-color:var(--ifm-color-success-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-success-dark)}.alert--info{--ifm-alert-background-color:var(--ifm-color-info-contrast-background);--ifm-alert-background-color-highlight:#54c7ec26;--ifm-alert-foreground-color:var(--ifm-color-info-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-info-dark)}.alert--warning{--ifm-alert-background-color:var(--ifm-color-warning-contrast-background);--ifm-alert-background-color-highlight:#ffba0026;--ifm-alert-foreground-color:var(--ifm-color-warning-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-warning-dark)}.alert--danger{--ifm-alert-background-color:var(--ifm-color-danger-contrast-background);--ifm-alert-background-color-highlight:#fa383e26;--ifm-alert-foreground-color:var(--ifm-color-danger-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-danger-dark)}.alert{--ifm-code-background:var(--ifm-alert-background-color-highlight);--ifm-link-color:var(--ifm-alert-foreground-color);--ifm-link-hover-color:var(--ifm-alert-foreground-color);--ifm-link-decoration:underline;--ifm-tabs-color:var(--ifm-alert-foreground-color);--ifm-tabs-color-active:var(--ifm-alert-foreground-color);--ifm-tabs-color-active-border:var(--ifm-alert-border-color);background-color:var(--ifm-alert-background-color);border:var(--ifm-alert-border-width) solid var(--ifm-alert-border-color);border-left-width:var(--ifm-alert-border-left-width);border-radius:var(--ifm-alert-border-radius);box-shadow:var(--ifm-alert-shadow);padding:var(--ifm-alert-padding-vertical) var(--ifm-alert-padding-horizontal)}.alert__heading{align-items:center;display:flex;font:700 var(--ifm-h5-font-size)/var(--ifm-heading-line-height) var(--ifm-heading-font-family);margin-bottom:.5rem}.alert__icon{display:inline-flex;margin-right:.4em}.alert__icon svg{fill:var(--ifm-alert-foreground-color);stroke:var(--ifm-alert-foreground-color);stroke-width:0}.alert .close{margin:calc(var(--ifm-alert-padding-vertical)*-1) calc(var(--ifm-alert-padding-horizontal)*-1) 0 0;opacity:.75}.alert .close:focus,.alert .close:hover{opacity:1}.alert a{text-decoration-color:var(--ifm-alert-border-color)}.alert a:hover{text-decoration-thickness:2px}.avatar{column-gap:var(--ifm-avatar-intro-margin);display:flex}.avatar__photo{border-radius:50%;display:block;height:var(--ifm-avatar-photo-size);overflow:hidden;width:var(--ifm-avatar-photo-size)}.card--full-height,.navbar__logo img{height:100%}.avatar__photo--sm{--ifm-avatar-photo-size:2rem}.avatar__photo--lg{--ifm-avatar-photo-size:4rem}.avatar__photo--xl{--ifm-avatar-photo-size:6rem}.avatar__intro{display:flex;flex:1 1;flex-direction:column;justify-content:center;text-align:var(--ifm-avatar-intro-alignment)}.badge,.breadcrumbs__item,.breadcrumbs__link,.button,.dropdown>.navbar__link:after{display:inline-block}.avatar__name{font:700 var(--ifm-h4-font-size)/var(--ifm-heading-line-height) var(--ifm-font-family-base)}.avatar__subtitle{margin-top:.25rem}.avatar--vertical{--ifm-avatar-intro-alignment:center;--ifm-avatar-intro-margin:0.5rem;align-items:center;flex-direction:column}.badge{background-color:var(--ifm-badge-background-color);border:var(--ifm-badge-border-width) solid var(--ifm-badge-border-color);border-radius:var(--ifm-badge-border-radius);color:var(--ifm-badge-color);font-size:75%;font-weight:var(--ifm-font-weight-bold);line-height:1;padding:var(--ifm-badge-padding-vertical) var(--ifm-badge-padding-horizontal)}.badge--primary{--ifm-badge-background-color:var(--ifm-color-primary)}.badge--secondary{--ifm-badge-background-color:var(--ifm-color-secondary);color:var(--ifm-color-black)}.breadcrumbs__link,.button.button--secondary.button--outline:not(.button--active):not(:hover){color:var(--ifm-font-color-base)}.badge--success{--ifm-badge-background-color:var(--ifm-color-success)}.badge--info{--ifm-badge-background-color:var(--ifm-color-info)}.badge--warning{--ifm-badge-background-color:var(--ifm-color-warning)}.badge--danger{--ifm-badge-background-color:var(--ifm-color-danger)}.breadcrumbs{margin-bottom:0;padding-left:0}.breadcrumbs__item:not(:last-child):after{background:var(--ifm-breadcrumb-separator) center;content:" ";display:inline-block;filter:var(--ifm-breadcrumb-separator-filter);height:calc(var(--ifm-breadcrumb-separator-size)*var(--ifm-breadcrumb-size-multiplier)*var(--ifm-breadcrumb-separator-size-multiplier));margin:0 var(--ifm-breadcrumb-spacing);opacity:.5;width:calc(var(--ifm-breadcrumb-separator-size)*var(--ifm-breadcrumb-size-multiplier)*var(--ifm-breadcrumb-separator-size-multiplier))}.breadcrumbs__item--active .breadcrumbs__link{background:var(--ifm-breadcrumb-item-background-active);color:var(--ifm-breadcrumb-color-active)}.breadcrumbs__link{border-radius:var(--ifm-breadcrumb-border-radius);font-size:calc(1rem*var(--ifm-breadcrumb-size-multiplier));padding:calc(var(--ifm-breadcrumb-padding-vertical)*var(--ifm-breadcrumb-size-multiplier)) calc(var(--ifm-breadcrumb-padding-horizontal)*var(--ifm-breadcrumb-size-multiplier));transition-duration:var(--ifm-transition-fast);transition-property:background,color}.breadcrumbs__link:any-link:hover,.breadcrumbs__link:link:hover,.breadcrumbs__link:visited:hover,area[href].breadcrumbs__link:hover{background:var(--ifm-breadcrumb-item-background-active);text-decoration:none}.breadcrumbs--sm{--ifm-breadcrumb-size-multiplier:0.8}.breadcrumbs--lg{--ifm-breadcrumb-size-multiplier:1.2}.button{background-color:var(--ifm-button-background-color);border:var(--ifm-button-border-width) solid var(--ifm-button-border-color);border-radius:var(--ifm-button-border-radius);cursor:pointer;font-size:calc(.875rem*var(--ifm-button-size-multiplier));font-weight:var(--ifm-button-font-weight);line-height:1.5;padding:calc(var(--ifm-button-padding-vertical)*var(--ifm-button-size-multiplier)) calc(var(--ifm-button-padding-horizontal)*var(--ifm-button-size-multiplier));text-align:center;transition-duration:var(--ifm-button-transition-duration);transition-property:color,background,border-color;-webkit-user-select:none;user-select:none;white-space:nowrap}.button,.button:hover{color:var(--ifm-button-color)}.button--outline{--ifm-button-color:var(--ifm-button-border-color)}.button--outline:hover{--ifm-button-background-color:var(--ifm-button-border-color)}.button--link{--ifm-button-border-color:#0000;color:var(--ifm-link-color);text-decoration:var(--ifm-link-decoration)}.button--link.button--active,.button--link:active,.button--link:hover{color:var(--ifm-link-hover-color);text-decoration:var(--ifm-link-hover-decoration)}.button.disabled,.button:disabled,.button[disabled]{opacity:.65;pointer-events:none}.button--sm{--ifm-button-size-multiplier:0.8}.button--lg{--ifm-button-size-multiplier:1.35}.button--block{display:block;width:100%}.button.button--secondary{color:var(--ifm-color-gray-900)}:where(.button--primary){--ifm-button-background-color:var(--ifm-color-primary);--ifm-button-border-color:var(--ifm-color-primary)}:where(.button--primary):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-primary-dark);--ifm-button-border-color:var(--ifm-color-primary-dark)}.button--primary.button--active,.button--primary:active{--ifm-button-background-color:var(--ifm-color-primary-darker);--ifm-button-border-color:var(--ifm-color-primary-darker)}:where(.button--secondary){--ifm-button-background-color:var(--ifm-color-secondary);--ifm-button-border-color:var(--ifm-color-secondary)}:where(.button--secondary):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-secondary-dark);--ifm-button-border-color:var(--ifm-color-secondary-dark)}.button--secondary.button--active,.button--secondary:active{--ifm-button-background-color:var(--ifm-color-secondary-darker);--ifm-button-border-color:var(--ifm-color-secondary-darker)}:where(.button--success){--ifm-button-background-color:var(--ifm-color-success);--ifm-button-border-color:var(--ifm-color-success)}:where(.button--success):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-success-dark);--ifm-button-border-color:var(--ifm-color-success-dark)}.button--success.button--active,.button--success:active{--ifm-button-background-color:var(--ifm-color-success-darker);--ifm-button-border-color:var(--ifm-color-success-darker)}:where(.button--info){--ifm-button-background-color:var(--ifm-color-info);--ifm-button-border-color:var(--ifm-color-info)}:where(.button--info):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-info-dark);--ifm-button-border-color:var(--ifm-color-info-dark)}.button--info.button--active,.button--info:active{--ifm-button-background-color:var(--ifm-color-info-darker);--ifm-button-border-color:var(--ifm-color-info-darker)}:where(.button--warning){--ifm-button-background-color:var(--ifm-color-warning);--ifm-button-border-color:var(--ifm-color-warning)}:where(.button--warning):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-warning-dark);--ifm-button-border-color:var(--ifm-color-warning-dark)}.button--warning.button--active,.button--warning:active{--ifm-button-background-color:var(--ifm-color-warning-darker);--ifm-button-border-color:var(--ifm-color-warning-darker)}:where(.button--danger){--ifm-button-background-color:var(--ifm-color-danger);--ifm-button-border-color:var(--ifm-color-danger)}:where(.button--danger):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-danger-dark);--ifm-button-border-color:var(--ifm-color-danger-dark)}.button--danger.button--active,.button--danger:active{--ifm-button-background-color:var(--ifm-color-danger-darker);--ifm-button-border-color:var(--ifm-color-danger-darker)}.button-group{display:inline-flex;gap:var(--ifm-button-group-spacing)}.button-group>.button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}.button-group>.button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0}.button-group--block{display:flex;justify-content:stretch}.button-group--block>.button{flex-grow:1}.card{background-color:var(--ifm-card-background-color);border-radius:var(--ifm-card-border-radius);box-shadow:var(--ifm-global-shadow-lw);display:flex;flex-direction:column;overflow:hidden}.card__image{padding-top:var(--ifm-card-vertical-spacing)}.card__image:first-child{padding-top:0}.card__body,.card__footer,.card__header{padding:var(--ifm-card-vertical-spacing) var(--ifm-card-horizontal-spacing)}.card__body:not(:last-child),.card__footer:not(:last-child),.card__header:not(:last-child){padding-bottom:0}.card__body>:last-child,.card__footer>:last-child,.card__header>:last-child{margin-bottom:0}.card__footer{margin-top:auto}.table-of-contents{font-size:.8rem;margin-bottom:0;padding:var(--ifm-toc-padding-vertical) 0}.table-of-contents,.table-of-contents ul{list-style:none;padding-left:var(--ifm-toc-padding-horizontal)}.table-of-contents li{margin:var(--ifm-toc-padding-vertical) var(--ifm-toc-padding-horizontal)}.table-of-contents__left-border{border-left:1px solid var(--ifm-toc-border-color)}.table-of-contents__link{color:var(--ifm-toc-link-color);display:block}.table-of-contents__link--active,.table-of-contents__link--active code,.table-of-contents__link:hover,.table-of-contents__link:hover code{color:var(--ifm-color-primary);text-decoration:none}.close{color:var(--ifm-color-black);float:right;font-size:1.5rem;font-weight:var(--ifm-font-weight-bold);line-height:1;opacity:.5;padding:1rem;transition:opacity var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.close:hover{opacity:.7}.close:focus,.theme-code-block-highlighted-line .codeLineNumber_Tfdd:before{opacity:.8}.dropdown{display:inline-flex;font-weight:var(--ifm-dropdown-font-weight);position:relative;vertical-align:top}.dropdown--hoverable:hover .dropdown__menu,.dropdown--show .dropdown__menu{opacity:1;pointer-events:all;transform:translateY(-1px);visibility:visible}.dropdown--right .dropdown__menu{left:inherit;right:0}.dropdown--nocaret .navbar__link:after{content:none!important}.dropdown__menu{background-color:var(--ifm-dropdown-background-color);border-radius:var(--ifm-global-radius);box-shadow:var(--ifm-global-shadow-md);left:0;list-style:none;max-height:80vh;min-width:10rem;opacity:0;overflow-y:auto;padding:.5rem;pointer-events:none;position:absolute;top:calc(100% - var(--ifm-navbar-item-padding-vertical) + .3rem);transform:translateY(-.625rem);transition-duration:var(--ifm-transition-fast);transition-property:opacity,transform,visibility;transition-timing-function:var(--ifm-transition-timing-default);visibility:hidden;z-index:var(--ifm-z-index-dropdown)}.menu__caret,.menu__link,.menu__list-item-collapsible{border-radius:.25rem;transition:background var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.dropdown__link{border-radius:.25rem;color:var(--ifm-dropdown-link-color);display:block;font-size:.875rem;margin-top:.2rem;padding:.25rem .5rem;white-space:nowrap}.sr-only,.truncate{white-space:nowrap!important}.dropdown__link--active,.dropdown__link:hover{background-color:var(--ifm-dropdown-hover-background-color);color:var(--ifm-dropdown-link-color);text-decoration:none}.dropdown__link--active,.dropdown__link--active:hover{--ifm-dropdown-link-color:var(--ifm-link-color)}.dropdown>.navbar__link:after{border-color:currentcolor #0000;border-style:solid;border-width:.4em .4em 0;content:"";margin-left:.3em;position:relative;top:2px;transform:translateY(-50%)}.footer{background-color:var(--ifm-footer-background-color);color:var(--ifm-footer-color);padding:var(--ifm-footer-padding-vertical) var(--ifm-footer-padding-horizontal)}.footer--dark{--ifm-footer-background-color:#303846;--ifm-footer-color:var(--ifm-footer-link-color);--ifm-footer-link-color:var(--ifm-color-secondary);--ifm-footer-title-color:var(--ifm-color-white)}.footer__links{margin-bottom:1rem}.footer__link-item{color:var(--ifm-footer-link-color);line-height:2}.footer__link-item:hover{color:var(--ifm-footer-link-hover-color)}.footer__link-separator{margin:0 var(--ifm-footer-link-horizontal-spacing)}.footer__logo{margin-top:1rem;max-width:var(--ifm-footer-logo-max-width)}.footer__title{color:var(--ifm-footer-title-color);font:700 var(--ifm-h4-font-size)/var(--ifm-heading-line-height) var(--ifm-font-family-base);margin-bottom:var(--ifm-heading-margin-bottom)}.menu,.navbar__link{font-weight:var(--ifm-font-weight-semibold)}.docItemContainer_Djhp article>:first-child,.docItemContainer_Djhp header+*,.footer__item{margin-top:0}.admonitionContent_S0QG>:last-child,.collapsibleContent_i85q>:last-child,.footer__items,.tabItem_Ymn6>:last-child{margin-bottom:0}.codeBlockStandalone_MEMb,.twLandingPage legend,[type=checkbox]{padding:0}.hero{align-items:center;background-color:var(--ifm-hero-background-color);color:var(--ifm-hero-text-color);display:flex;padding:4rem 2rem}.hero--primary{--ifm-hero-background-color:var(--ifm-color-primary);--ifm-hero-text-color:var(--ifm-font-color-base-inverse)}.hero--dark{--ifm-hero-background-color:#303846;--ifm-hero-text-color:var(--ifm-color-white)}.hero__title,.title_f1Hy{font-size:3rem}.hero__subtitle{font-size:1.5rem}.menu__list{list-style:none;margin:0;padding-left:0}.menu__caret,.menu__link{padding:var(--ifm-menu-link-padding-vertical) var(--ifm-menu-link-padding-horizontal)}.menu__list .menu__list{flex:0 0 100%;margin-top:.25rem;padding-left:var(--ifm-menu-link-padding-horizontal)}.menu__list-item:not(:first-child){margin-top:.25rem}.menu__list-item--collapsed .menu__list{height:0;overflow:hidden}.details_lb9f[data-collapsed=false].isBrowser_bmU9>summary:before,.details_lb9f[open]:not(.isBrowser_bmU9)>summary:before,.menu__list-item--collapsed .menu__caret:before,.menu__list-item--collapsed .menu__link--sublist:after{transform:rotate(90deg)}.menu__list-item-collapsible{display:flex;flex-wrap:wrap;position:relative}.menu__caret:hover,.menu__link:hover,.menu__list-item-collapsible--active,.menu__list-item-collapsible:hover{background:var(--ifm-menu-color-background-hover)}.menu__list-item-collapsible .menu__link--active,.menu__list-item-collapsible .menu__link:hover{background:none!important}.menu__caret,.menu__link{align-items:center;display:flex}.navbar-sidebar,.navbar-sidebar__backdrop{bottom:0;opacity:0;transition-duration:var(--ifm-transition-fast);transition-timing-function:ease-in-out;visibility:hidden;left:0;top:0}.menu__link{color:var(--ifm-menu-color);flex:1;line-height:1.25}.menu__link:hover{color:var(--ifm-menu-color);text-decoration:none}.menu__caret:before,.menu__link--sublist-caret:after{content:"";height:1.25rem;transform:rotate(180deg);transition:transform var(--ifm-transition-fast) linear;width:1.25rem;filter:var(--ifm-menu-link-sublist-icon-filter)}.menu__link--sublist-caret:after{background:var(--ifm-menu-link-sublist-icon) 50%/2rem 2rem;margin-left:auto;min-width:1.25rem}.menu__link--active,.menu__link--active:hover{color:var(--ifm-menu-color-active)}.navbar__brand,.navbar__link{color:var(--ifm-navbar-link-color)}.menu__link--active:not(.menu__link--sublist){background-color:var(--ifm-menu-color-background-active)}.menu__caret:before{background:var(--ifm-menu-link-sublist-icon) 50%/2rem 2rem}.navbar--dark,html[data-theme=dark]{--ifm-menu-link-sublist-icon-filter:invert(100%) sepia(94%) saturate(17%) hue-rotate(223deg) brightness(104%) contrast(98%)}.navbar{background-color:var(--ifm-navbar-background-color);box-shadow:var(--ifm-navbar-shadow);height:var(--ifm-navbar-height);padding:var(--ifm-navbar-padding-vertical) var(--ifm-navbar-padding-horizontal)}.navbar,.navbar>.container,.navbar>.container-fluid{display:flex}.navbar--fixed-top{position:sticky;top:0;z-index:var(--ifm-z-index-fixed)}.navbar__inner{display:flex;flex-wrap:wrap;justify-content:space-between;width:100%}.navbar__brand{align-items:center;display:flex;margin-right:1rem;min-width:0}.navbar__brand:hover{color:var(--ifm-navbar-link-hover-color);text-decoration:none}.announcementBarContent_xLdY,.navbar__title{flex:1 1 auto}.navbar__toggle{display:none;margin-right:.5rem}.navbar__logo{flex:0 0 auto;height:2rem;margin-right:.5rem}.navbar__items{align-items:center;display:flex;flex:1;min-width:0}.navbar__items--center{flex:0 0 auto}.auth-method-box p,.deployment-method-box p,.navbar__items--center .navbar__brand,.twLandingPage blockquote,.twLandingPage dd,.twLandingPage dl,.twLandingPage figure,.twLandingPage h1,.twLandingPage h2,.twLandingPage h3,.twLandingPage h4,.twLandingPage h5,.twLandingPage h6,.twLandingPage hr,.twLandingPage p,pre{margin:0}.navbar__items--center+.navbar__items--right{flex:1}.navbar__items--right{flex:0 0 auto;justify-content:flex-end}.navbar__items--right>:last-child{padding-right:0}.navbar__item{display:inline-block;padding:var(--ifm-navbar-item-padding-vertical) var(--ifm-navbar-item-padding-horizontal)}#nprogress,.navbar__item.dropdown .navbar__link:not([href]){pointer-events:none}.navbar__link--active,.navbar__link:hover{color:var(--ifm-navbar-link-hover-color);text-decoration:none}.navbar--dark,.navbar--primary{--ifm-menu-color:var(--ifm-color-gray-300);--ifm-navbar-link-color:var(--ifm-color-gray-100);--ifm-navbar-search-input-background-color:#ffffff1a;--ifm-navbar-search-input-placeholder-color:#ffffff80;color:var(--ifm-color-white)}.navbar--dark{--ifm-navbar-background-color:#242526;--ifm-menu-color-background-active:#ffffff0d;--ifm-navbar-search-input-color:var(--ifm-color-white)}.navbar--primary{--ifm-navbar-background-color:var(--ifm-color-primary);--ifm-navbar-link-hover-color:var(--ifm-color-white);--ifm-menu-color-active:var(--ifm-color-white);--ifm-navbar-search-input-color:var(--ifm-color-emphasis-500)}.navbar__search-input{appearance:none;background:var(--ifm-navbar-search-input-background-color) var(--ifm-navbar-search-input-icon) no-repeat .75rem center/1rem 1rem;border:none;border-radius:2rem;color:var(--ifm-navbar-search-input-color);cursor:text;display:inline-block;font-size:.9rem;height:2rem;padding:0 .5rem 0 2.25rem;width:12.5rem}.navbar__search-input::placeholder{color:var(--ifm-navbar-search-input-placeholder-color)}.navbar-sidebar{background-color:var(--ifm-navbar-background-color);box-shadow:var(--ifm-global-shadow-md);position:fixed;transform:translate3d(-100%,0,0);transition-property:opacity,visibility,transform;width:var(--ifm-navbar-sidebar-width)}.navbar-sidebar--show .navbar-sidebar,.navbar-sidebar__items{transform:translateZ(0)}.navbar-sidebar--show .navbar-sidebar,.navbar-sidebar--show .navbar-sidebar__backdrop{opacity:1;visibility:visible}.navbar-sidebar__backdrop{background-color:#0009;position:fixed;right:0;transition-property:opacity,visibility}.navbar-sidebar__brand{align-items:center;box-shadow:var(--ifm-navbar-shadow);display:flex;flex:1;height:var(--ifm-navbar-height);padding:var(--ifm-navbar-padding-vertical) var(--ifm-navbar-padding-horizontal)}.hover\:shadow-lg:hover,.shadow-2xl,.shadow-lg,.shadow-sm{box-shadow:var(--tw-ring-offset-shadow,0 0 #0000),var(--tw-ring-shadow,0 0 #0000),var(--tw-shadow)!important}.navbar-sidebar__items{display:flex;height:calc(100% - var(--ifm-navbar-height));transition:transform var(--ifm-transition-fast) ease-in-out}.navbar-sidebar__items--show-secondary{transform:translate3d(calc((var(--ifm-navbar-sidebar-width))*-1),0,0)}.navbar-sidebar__item{flex-shrink:0;padding:.5rem;width:calc(var(--ifm-navbar-sidebar-width))}.navbar-sidebar__back{background:var(--ifm-menu-color-background-active);font-size:15px;font-weight:var(--ifm-button-font-weight);margin:0 0 .2rem -.5rem;padding:.6rem 1.5rem;position:relative;text-align:left;top:-.5rem;width:calc(100% + 1rem)}.navbar-sidebar__close{display:flex;margin-left:auto}.pagination{column-gap:var(--ifm-pagination-page-spacing);display:flex;font-size:var(--ifm-pagination-font-size);padding-left:0}.pagination--sm{--ifm-pagination-font-size:0.8rem;--ifm-pagination-padding-horizontal:0.8rem;--ifm-pagination-padding-vertical:0.2rem}.pagination--lg{--ifm-pagination-font-size:1.2rem;--ifm-pagination-padding-horizontal:1.2rem;--ifm-pagination-padding-vertical:0.3rem}.pagination__item{display:inline-flex}.pagination__item>span{padding:var(--ifm-pagination-padding-vertical)}.pagination__item--active .pagination__link{color:var(--ifm-pagination-color-active)}.pagination__item--active .pagination__link,.pagination__item:not(.pagination__item--active):hover .pagination__link{background:var(--ifm-pagination-item-active-background)}.pagination__item--disabled,.pagination__item[disabled]{opacity:.25;pointer-events:none}.pagination__link{border-radius:var(--ifm-pagination-border-radius);color:var(--ifm-font-color-base);display:inline-block;padding:var(--ifm-pagination-padding-vertical) var(--ifm-pagination-padding-horizontal);transition:background var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.pagination__link:hover,.sidebarItemLink_mo7H:hover,a:hover{text-decoration:none}.pagination-nav{grid-gap:var(--ifm-spacing-horizontal);display:grid;gap:var(--ifm-spacing-horizontal);grid-template-columns:repeat(2,1fr)}.pagination-nav__link{border:1px solid var(--ifm-color-emphasis-300);border-radius:var(--ifm-pagination-nav-border-radius);display:block;height:100%;line-height:var(--ifm-heading-line-height);padding:var(--ifm-global-spacing);transition:border-color var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.pagination-nav__link:hover{border-color:var(--ifm-pagination-nav-color-hover);text-decoration:none}.DocSearch-Hit[aria-selected=true] mark,.content_knG7 a{text-decoration:underline}.pagination-nav__link--next{grid-column:2/3;text-align:right}.pagination-nav__label{font-size:var(--ifm-h4-font-size);font-weight:var(--ifm-heading-font-weight);word-break:break-word}.pagination-nav__link--prev .pagination-nav__label:before{content:"« "}.pagination-nav__link--next .pagination-nav__label:after{content:" »"}.pagination-nav__sublabel{color:var(--ifm-color-content-secondary);font-size:var(--ifm-h5-font-size);font-weight:var(--ifm-font-weight-semibold);margin-bottom:.25rem}.pills__item,.tabs{font-weight:var(--ifm-font-weight-bold)}.pills{display:flex;gap:var(--ifm-pills-spacing);padding-left:0}.pills__item{border-radius:.5rem;cursor:pointer;display:inline-block;padding:.25rem 1rem;transition:background var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.tabs,:not(.containsTaskList_mC6p>li)>.containsTaskList_mC6p{padding-left:0}.pills__item--active{color:var(--ifm-pills-color-active)}.pills__item--active,.pills__item:not(.pills__item--active):hover{background:var(--ifm-pills-color-background-active)}.pills--block{justify-content:stretch}.pills--block .pills__item{flex-grow:1;text-align:center}.tabs{color:var(--ifm-tabs-color);display:flex;margin-bottom:0;overflow-x:auto}.tabs__item{border-bottom:3px solid #0000;border-radius:var(--ifm-global-radius);cursor:pointer;display:inline-flex;padding:var(--ifm-tabs-padding-vertical) var(--ifm-tabs-padding-horizontal);transition:background-color var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.transition,.transition-all,.transition-colors{transition-timing-function:cubic-bezier(.4,0,.2,1)!important}.duration-150,.transition,.transition-all,.transition-colors{transition-duration:.15s!important}.tabs__item--active{border-bottom-color:var(--ifm-tabs-color-active-border);border-bottom-left-radius:0;border-bottom-right-radius:0;color:var(--ifm-tabs-color-active)}.tabs__item:hover{background-color:var(--ifm-hover-overlay)}.tabs--block{justify-content:stretch}.tabs--block .tabs__item{flex-grow:1;justify-content:center}html[data-theme=dark]{--ifm-color-scheme:dark;--ifm-color-emphasis-0:var(--ifm-color-gray-1000);--ifm-color-emphasis-100:var(--ifm-color-gray-900);--ifm-color-emphasis-200:var(--ifm-color-gray-800);--ifm-color-emphasis-300:var(--ifm-color-gray-700);--ifm-color-emphasis-400:var(--ifm-color-gray-600);--ifm-color-emphasis-600:var(--ifm-color-gray-400);--ifm-color-emphasis-700:var(--ifm-color-gray-300);--ifm-color-emphasis-800:var(--ifm-color-gray-200);--ifm-color-emphasis-900:var(--ifm-color-gray-100);--ifm-color-emphasis-1000:var(--ifm-color-gray-0);--ifm-background-color:#1b1b1d;--ifm-background-surface-color:#242526;--ifm-hover-overlay:#ffffff0d;--ifm-color-content:#e3e3e3;--ifm-color-content-secondary:#fff;--ifm-breadcrumb-separator-filter:invert(64%) sepia(11%) saturate(0%) hue-rotate(149deg) brightness(99%) contrast(95%);--ifm-code-background:#ffffff1a;--ifm-scrollbar-track-background-color:#444;--ifm-scrollbar-thumb-background-color:#686868;--ifm-scrollbar-thumb-hover-background-color:#7a7a7a;--ifm-table-stripe-background:#ffffff12;--ifm-toc-border-color:var(--ifm-color-emphasis-200);--ifm-color-primary-contrast-background:#102445;--ifm-color-primary-contrast-foreground:#ebf2fc;--ifm-color-secondary-contrast-background:#474748;--ifm-color-secondary-contrast-foreground:#fdfdfe;--ifm-color-success-contrast-background:#003100;--ifm-color-success-contrast-foreground:#e6f6e6;--ifm-color-info-contrast-background:#193c47;--ifm-color-info-contrast-foreground:#eef9fd;--ifm-color-warning-contrast-background:#4d3800;--ifm-color-warning-contrast-foreground:#fff8e6;--ifm-color-danger-contrast-background:#4b1113;--ifm-color-danger-contrast-foreground:#ffebec;--docsearch-text-color:#f5f6f7;--docsearch-container-background:#090a11cc;--docsearch-modal-background:#15172a;--docsearch-modal-shadow:inset 1px 1px 0 0 #2c2e40,0 3px 8px 0 #000309;--docsearch-searchbox-background:#090a11;--docsearch-searchbox-focus-background:#000;--docsearch-hit-color:#bec3c9;--docsearch-hit-shadow:none;--docsearch-hit-background:#090a11;--docsearch-key-gradient:linear-gradient(-26.5deg,#565872,#31355b);--docsearch-key-shadow:inset 0 -2px 0 0 #282d55,inset 0 0 1px 1px #51577d,0 2px 2px 0 #0304094d;--docsearch-footer-background:#1e2136;--docsearch-footer-shadow:inset 0 1px 0 0 #494c6a80,0 -4px 8px 0 #0003;--docsearch-logo-color:#fff;--docsearch-muted-color:#7f8497}#nprogress .bar{background:var(--docusaurus-progress-bar-color);height:2px;left:0;position:fixed;top:0;width:100%;z-index:1031}#nprogress .peg{box-shadow:0 0 10px var(--docusaurus-progress-bar-color),0 0 5px var(--docusaurus-progress-bar-color);height:100%;opacity:1;position:absolute;right:0;transform:rotate(3deg) translateY(-4px);width:100px}*,::backdrop,:after,:before{--tw-border-spacing-x:0;--tw-border-spacing-y:0;--tw-translate-x:0;--tw-translate-y:0;--tw-rotate:0;--tw-skew-x:0;--tw-skew-y:0;--tw-scale-x:1;--tw-scale-y:1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness:proximity;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:#3b82f680;--tw-ring-offset-shadow:0 0 #0000;--tw-ring-shadow:0 0 #0000;--tw-shadow:0 0 #0000;--tw-shadow-colored:0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: }.focus\:ring-2:focus,.ring-0{--tw-ring-offset-shadow:var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color)!important}.container{width:100%}.sr-only{clip:rect(0,0,0,0)!important;border-width:0!important;height:1px!important;margin:-1px!important;overflow:hidden!important;padding:0!important;position:absolute!important;width:1px!important}.pointer-events-none{pointer-events:none!important}.visible{visibility:visible!important}.static{position:static!important}.fixed{position:fixed!important}.absolute{position:absolute!important}.relative{position:relative!important}.sticky{position:sticky!important}.inset-0{inset:0!important}.-inset-y-0,.inset-y-0{bottom:0!important;top:0!important}.-left-\[50\%\]{left:-50%!important}.left-0{left:0!important}.right-4{right:1rem!important}.top-0{top:0!important}.top-4{top:1rem!important}.top-\[1800px\]{top:1800px!important}.z-10{z-index:10!important}.z-50{z-index:50!important}.col-span-12{grid-column:span 12/span 12!important}.col-span-8{grid-column:span 8/span 8!important}.col-start-3{grid-column-start:3!important}.mx-3{margin-left:.75rem!important;margin-right:.75rem!important}.mx-auto{margin-left:auto!important;margin-right:auto!important}.-mr-2{margin-right:-.5rem!important}.mb-10{margin-bottom:2.5rem!important}.mb-12{margin-bottom:3rem!important}.mb-6{margin-bottom:1.5rem!important}.ml-3{margin-left:.75rem!important}.ml-6{margin-left:1.5rem!important}.mt-16{margin-top:4rem!important}.mt-24{margin-top:6rem!important}.mt-3{margin-top:.75rem!important}.mt-6{margin-top:1.5rem!important}.block{display:block!important}.inline-block{display:inline-block!important}.inline{display:inline!important}.flex{display:flex!important}.inline-flex{display:inline-flex!important}.grid{display:grid!important}.hidden{display:none!important}.h-11{height:2.75rem!important}.h-16{height:4rem!important}.h-2{height:.5rem!important}.h-20{height:5rem!important}.h-28{height:7rem!important}.h-3{height:.75rem!important}.h-40{height:10rem!important}.h-5{height:1.25rem!important}.h-6{height:1.5rem!important}.h-60{height:15rem!important}.h-64{height:16rem!important}.h-8{height:2rem!important}.h-full{height:100%!important}.h-px{height:1px!important}.h-screen{height:100vh!important}.min-h-screen{min-height:100vh!important}.w-11{width:2.75rem!important}.w-2{width:.5rem!important}.w-24{width:6rem!important}.w-3{width:.75rem!important}.w-32{width:8rem!important}.w-5{width:1.25rem!important}.w-6{width:1.5rem!important}.w-8{width:2rem!important}.w-\[200\%\]{width:200%!important}.w-full{width:100%!important}.w-screen{width:100vw!important}.min-w-full{min-width:100%!important}.max-w-3xl{max-width:48rem!important}.max-w-lg{max-width:32rem!important}.flex-1{flex:1 1 0%!important}.flex-shrink-0{flex-shrink:0!important}.translate-x-0{--tw-translate-x:0px!important}.transform,.translate-x-0,.translate-x-5,.translate-y-0,.translate-y-1{transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))!important}.translate-x-5{--tw-translate-x:1.25rem!important}.translate-y-0{--tw-translate-y:0px!important}.translate-y-1{--tw-translate-y:0.25rem!important}.cursor-pointer{cursor:pointer!important}.select-none{-webkit-user-select:none!important;user-select:none!important}.resize{resize:both!important}.appearance-none{appearance:none!important}.grid-cols-1{grid-template-columns:repeat(1,minmax(0,1fr))!important}.grid-cols-12{grid-template-columns:repeat(12,minmax(0,1fr))!important}.grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))!important}.flex-row{flex-direction:row!important}.flex-col{flex-direction:column!important}.items-start{align-items:flex-start!important}.items-end{align-items:flex-end!important}.items-center{align-items:center!important}.items-stretch{align-items:stretch!important}.justify-center{justify-content:center!important}.justify-between{justify-content:space-between!important}.gap-1{gap:.25rem!important}.gap-2{gap:.5rem!important}.gap-3{gap:.75rem!important}.gap-4{gap:1rem!important}.gap-5{gap:1.25rem!important}.gap-6{gap:1.5rem!important}.gap-8{gap:2rem!important}.gap-y-4{row-gap:1rem!important}.space-x-1>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0!important;margin-left:calc(.25rem*(1 - var(--tw-space-x-reverse)))!important;margin-right:calc(.25rem*var(--tw-space-x-reverse))!important}.space-x-2>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0!important;margin-left:calc(.5rem*(1 - var(--tw-space-x-reverse)))!important;margin-right:calc(.5rem*var(--tw-space-x-reverse))!important}.space-x-3>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0!important;margin-left:calc(.75rem*(1 - var(--tw-space-x-reverse)))!important;margin-right:calc(.75rem*var(--tw-space-x-reverse))!important}.space-x-4>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0!important;margin-left:calc(1rem*(1 - var(--tw-space-x-reverse)))!important;margin-right:calc(1rem*var(--tw-space-x-reverse))!important}.space-y-1>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(.25rem*var(--tw-space-y-reverse))!important;margin-top:calc(.25rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-12>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(3rem*var(--tw-space-y-reverse))!important;margin-top:calc(3rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-16>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(4rem*var(--tw-space-y-reverse))!important;margin-top:calc(4rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-2>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(.5rem*var(--tw-space-y-reverse))!important;margin-top:calc(.5rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-3>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(.75rem*var(--tw-space-y-reverse))!important;margin-top:calc(.75rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-4>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(1rem*var(--tw-space-y-reverse))!important;margin-top:calc(1rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-6>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(1.5rem*var(--tw-space-y-reverse))!important;margin-top:calc(1.5rem*(1 - var(--tw-space-y-reverse)))!important}.divide-y>:not([hidden])~:not([hidden]){--tw-divide-y-reverse:0!important;border-bottom-width:calc(1px*var(--tw-divide-y-reverse))!important;border-top-width:calc(1px*(1 - var(--tw-divide-y-reverse)))!important}.divide-neutral-300>:not([hidden])~:not([hidden]){--tw-divide-opacity:1!important;border-color:rgb(212 212 212/var(--tw-divide-opacity))!important}.divide-white>:not([hidden])~:not([hidden]){--tw-divide-opacity:1!important;border-color:rgb(255 255 255/var(--tw-divide-opacity))!important}.self-center{align-self:center!important}.self-stretch{align-self:stretch!important}.overflow-auto{overflow:auto!important}.DocSearch--active,.overflow-hidden{overflow:hidden!important}.overflow-y-hidden{overflow-y:hidden!important}.overflow-y-scroll{overflow-y:scroll!important}.truncate{overflow:hidden!important;text-overflow:ellipsis!important}.whitespace-pre-wrap{white-space:pre-wrap!important}.rounded{border-radius:.25rem!important}.rounded-2xl{border-radius:1rem!important}.rounded-full{border-radius:9999px!important}.rounded-lg{border-radius:.5rem!important}.rounded-md{border-radius:.375rem!important}.rounded-xl{border-radius:.75rem!important}.rounded-b-md{border-bottom-left-radius:.375rem!important;border-bottom-right-radius:.375rem!important}.rounded-b-none{border-bottom-left-radius:0!important;border-bottom-right-radius:0!important}.rounded-t-md{border-top-left-radius:.375rem!important;border-top-right-radius:.375rem!important}.rounded-t-none{border-top-left-radius:0!important;border-top-right-radius:0!important}.border{border-width:1px!important}.border-2{border-width:2px!important}.border-b{border-bottom-width:1px!important}.border-b-2{border-bottom-width:2px!important}.border-l{border-left-width:1px!important}.border-r{border-right-width:1px!important}.border-t{border-top-width:1px!important}.border-blue-500{border-color:rgb(59 130 246/var(--tw-border-opacity))!important}.border-fuchsia-600{border-color:rgb(192 38 211/var(--tw-border-opacity))!important}.border-green-600{border-color:rgb(22 163 74/var(--tw-border-opacity))!important}.border-neutral-200\/20{border-color:#e5e5e533!important}.border-neutral-300{border-color:rgb(212 212 212/var(--tw-border-opacity))!important}.border-neutral-500{border-color:rgb(115 115 115/var(--tw-border-opacity))!important}.border-transparent{border-color:#0000!important}.border-yellow-500,.hover\:border-yellow-500:hover{--tw-border-opacity:1!important;border-color:rgb(234 179 8/var(--tw-border-opacity))!important}.border-yellow-500\/25{border-color:#eab30840!important}.border-yellow-500\/75{border-color:#eab308bf!important}.border-yellow-600{border-color:rgb(202 138 4/var(--tw-border-opacity))!important}.border-l-neutral-400\/50{border-left-color:#a3a3a380!important}.bg-\[\#F3EDE0\]{background-color:rgb(243 237 224/var(--tw-bg-opacity))!important}.bg-\[\#f5f4f0\]{background-color:rgb(245 244 240/var(--tw-bg-opacity))!important}.bg-\[\#f5f5f5\]{background-color:rgb(245 245 245/var(--tw-bg-opacity))!important}.bg-\[--custom-blog-card-background-color\]{background-color:var(--custom-blog-card-background-color)!important}.bg-fuchsia-50{background-color:rgb(253 244 255/var(--tw-bg-opacity))!important}.bg-gray-200{background-color:rgb(229 231 235/var(--tw-bg-opacity))!important}.bg-green-50{background-color:rgb(240 253 244/var(--tw-bg-opacity))!important}.bg-neutral-100\/50{background-color:#f5f5f580!important}.bg-neutral-500{background-color:rgb(115 115 115/var(--tw-bg-opacity))!important}.bg-neutral-600,.hover\:bg-neutral-600:hover{--tw-bg-opacity:1!important;background-color:rgb(82 82 82/var(--tw-bg-opacity))!important}.bg-neutral-600\/20{background-color:#52525233!important}.bg-neutral-700{background-color:rgb(64 64 64/var(--tw-bg-opacity))!important}.bg-slate-50{background-color:rgb(248 250 252/var(--tw-bg-opacity))!important}.bg-transparent{background-color:initial!important}.bg-white{background-color:rgb(255 255 255/var(--tw-bg-opacity))!important}.bg-yellow-50{background-color:rgb(254 252 232/var(--tw-bg-opacity))!important}.bg-yellow-500{background-color:rgb(234 179 8/var(--tw-bg-opacity))!important}.bg-yellow-500\/20{background-color:#eab30833!important}.bg-yellow-500\/25{background-color:#eab30840!important}.bg-yellow-500\/5{background-color:#eab3080d!important}.object-cover{object-fit:cover!important}.p-3{padding:.75rem!important}.p-5{padding:1.25rem!important}.p-6{padding:1.5rem!important}.px-2\.5{padding-left:.625rem!important;padding-right:.625rem!important}.px-3{padding-left:.75rem!important;padding-right:.75rem!important}.px-5{padding-left:1.25rem!important;padding-right:1.25rem!important}.px-6{padding-left:1.5rem!important;padding-right:1.5rem!important}.py-0\.5{padding-bottom:.125rem!important;padding-top:.125rem!important}.py-1\.5{padding-bottom:.375rem!important;padding-top:.375rem!important}.py-16{padding-bottom:4rem!important;padding-top:4rem!important}.py-5{padding-bottom:1.25rem!important;padding-top:1.25rem!important}.py-6{padding-bottom:1.5rem!important;padding-top:1.5rem!important}.pb-5{padding-bottom:1.25rem!important}.pb-\[56\.25\%\]{padding-bottom:56.25%!important}.pl-3{padding-left:.75rem!important}.pr-5{padding-right:1.25rem!important}.pt-24{padding-top:6rem!important}.text-left{text-align:left!important}.text-center{text-align:center!important}.text-2xl{font-size:1.5rem!important;line-height:2rem!important}.text-4xl{font-size:2.25rem!important;line-height:2.5rem!important}.text-\[11px\]{font-size:11px!important}.text-base{font-size:1rem!important;line-height:1.5rem!important}.text-lg{font-size:1.125rem!important;line-height:1.75rem!important}.text-sm{font-size:.875rem!important;line-height:1.25rem!important}.text-xl{font-size:1.25rem!important;line-height:1.75rem!important}.leading-4,.text-xs{line-height:1rem!important}.text-xs{font-size:.75rem!important}.font-bold{font-weight:700!important}.font-extrabold{font-weight:800!important}.font-medium{font-weight:500!important}.font-semibold{font-weight:600!important}.uppercase{text-transform:uppercase!important}.leading-6{line-height:1.5rem!important}.leading-tight{line-height:1.25!important}.tracking-wider{letter-spacing:.05em!important}.text-\[--custom-blog-card-timestamp-color\]{color:var(--custom-blog-card-timestamp-color)!important}.text-blue-500{color:rgb(59 130 246/var(--tw-text-opacity))!important}.text-fuchsia-600{color:rgb(192 38 211/var(--tw-text-opacity))!important}.text-green-600{color:rgb(22 163 74/var(--tw-text-opacity))!important}.text-neutral-400{color:rgb(163 163 163/var(--tw-text-opacity))!important}.hover\:text-neutral-500:hover,.text-neutral-500{color:rgb(115 115 115/var(--tw-text-opacity))!important}.text-neutral-600{color:rgb(82 82 82/var(--tw-text-opacity))!important}.text-neutral-700{color:rgb(64 64 64/var(--tw-text-opacity))!important}.text-neutral-800{color:rgb(38 38 38/var(--tw-text-opacity))!important}.text-white{color:rgb(255 255 255/var(--tw-text-opacity))!important}.text-yellow-400{color:rgb(250 204 21/var(--tw-text-opacity))!important}.group:hover .group-hover\:text-yellow-500,.hover\:text-yellow-500:hover,.text-yellow-500{--tw-text-opacity:1!important;color:rgb(234 179 8/var(--tw-text-opacity))!important}.text-yellow-600{color:rgb(202 138 4/var(--tw-text-opacity))!important}.underline{text-decoration-line:underline!important}.decoration-neutral-500{text-decoration-color:#737373!important}.decoration-yellow-500{text-decoration-color:#eab308!important}.decoration-2{text-decoration-thickness:2px!important}.opacity-0{opacity:0!important}.opacity-100,.theme-code-block:hover .copyButtonCopied_obH4{opacity:1!important}.opacity-80{opacity:.8!important}.shadow-2xl{--tw-shadow:0 25px 50px -12px #00000040!important;--tw-shadow-colored:0 25px 50px -12px var(--tw-shadow-color)!important}.hover\:shadow-lg:hover,.shadow-lg{--tw-shadow-colored:0 10px 15px -3px var(--tw-shadow-color),0 4px 6px -4px var(--tw-shadow-color)!important}.shadow-lg{--tw-shadow:0 10px 15px -3px #0000001a,0 4px 6px -4px #0000001a!important}.shadow-sm{--tw-shadow:0 1px 2px 0 #0000000d!important;--tw-shadow-colored:0 1px 2px 0 var(--tw-shadow-color)!important}.hover\:shadow-yellow-500\/25:hover,.shadow-yellow-500\/25{--tw-shadow-color:#eab30840!important;--tw-shadow:var(--tw-shadow-colored)!important}.ring-0{--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(var(--tw-ring-offset-width)) var(--tw-ring-color)!important;box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow,0 0 #0000)!important}.drop-shadow-sm{--tw-drop-shadow:drop-shadow(0 1px 1px #0000000d)!important}.drop-shadow-sm,.filter{filter:var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow)!important}.backdrop-blur-sm{--tw-backdrop-blur:blur(4px)!important;-webkit-backdrop-filter:var(--tw-backdrop-blur) var(--tw-backdrop-brightness) var(--tw-backdrop-contrast) var(--tw-backdrop-grayscale) var(--tw-backdrop-hue-rotate) var(--tw-backdrop-invert) var(--tw-backdrop-opacity) var(--tw-backdrop-saturate) var(--tw-backdrop-sepia)!important;backdrop-filter:var(--tw-backdrop-blur) var(--tw-backdrop-brightness) var(--tw-backdrop-contrast) var(--tw-backdrop-grayscale) var(--tw-backdrop-hue-rotate) var(--tw-backdrop-invert) var(--tw-backdrop-opacity) var(--tw-backdrop-saturate) var(--tw-backdrop-sepia)!important}.transition{transition-property:color,background-color,border-color,text-decoration-color,fill,stroke,opacity,box-shadow,transform,filter,backdrop-filter,-webkit-backdrop-filter!important}.transition-all{transition-property:all!important}.transition-colors{transition-property:color,background-color,border-color,text-decoration-color,fill,stroke!important}.duration-200{transition-duration:.2s!important}.ease-in{transition-timing-function:cubic-bezier(.4,0,1,1)!important}.ease-in-out{transition-timing-function:cubic-bezier(.4,0,.2,1)!important}.ease-out{transition-timing-function:cubic-bezier(0,0,.2,1)!important}.blog-list-page{background-color:var(--custom-blog-list-background-color)}.token.boolean,.token.constant,.token.entity,.token.inserted,.token.number,.token.property,.token.regex,.token.symbol,.token.type-class-name,.token.url,.token.variable{color:#36acaa}.token.annotation{color:#747474!important}:root{--docusaurus-progress-bar-color:var(--ifm-color-primary);--custom-background-color:#fdfdfd;--custom-background-color-diff:#f4f4f4;--custom-shadow-lw:0 3px 5px 0px #0000001a;--custom-border-radius:3px;--custom-border-radius-md:6px;--custom-discord-color:#8a9cff;--custom-wasp-color:#fc0;--ifm-h3-font-size:1.3rem;--custom-blog-list-background-color:#f5f5f5;--custom-blog-card-timestamp-color:#737373;--custom-blog-card-background-color:#fff;--ifm-container-width-xl:1280px;--ifm-font-family-base:"Inter",sans-serif;--ifm-color-primary:#bf9900;--ifm-color-primary-dark:#8a6f04;--ifm-color-primary-darker:#1fa588;--ifm-color-primary-darkest:#1a8870;--ifm-color-primary-light:#46cbae;--ifm-color-primary-lighter:#66d4bd;--ifm-color-primary-lightest:#92e0d0;--ifm-code-font-size:95%;--ifm-code-background-dark:#292d3e;--ifm-global-radius:0;--ifm-button-background-color:var(--custom-background-color);--ifm-button-border-radius:var(--custom-border-radius);--ifm-code-border-radius:var(--custom-border-radius);--ifm-heading-font-weight:600;--ifm-col-spacing-vertical:0.5rem;--docusaurus-highlighted-code-line-bg:#e8edf2;--ifm-menu-color:var(--ifm-color-gray-800);--sidebar-item-level-1-color:var(--ifm-color-primary);--sidebar-item-level-1-spacing:1em;--docusaurus-announcement-bar-height:auto;--docusaurus-collapse-button-bg:#0000;--docusaurus-collapse-button-bg-hover:#0000001a;--doc-sidebar-width:300px;--doc-sidebar-hidden-width:30px;--docsearch-primary-color:#5468ff;--docsearch-text-color:#1c1e21;--docsearch-spacing:12px;--docsearch-icon-stroke-width:1.4;--docsearch-highlight-color:var(--docsearch-primary-color);--docsearch-muted-color:#969faf;--docsearch-container-background:#656c85cc;--docsearch-logo-color:#5468ff;--docsearch-modal-width:560px;--docsearch-modal-height:600px;--docsearch-modal-background:#f5f6f7;--docsearch-modal-shadow:inset 1px 1px 0 0 #ffffff80,0 3px 8px 0 #555a64;--docsearch-searchbox-height:56px;--docsearch-searchbox-background:#ebedf0;--docsearch-searchbox-focus-background:#fff;--docsearch-searchbox-shadow:inset 0 0 0 2px var(--docsearch-primary-color);--docsearch-hit-height:56px;--docsearch-hit-color:#444950;--docsearch-hit-active-color:#fff;--docsearch-hit-background:#fff;--docsearch-hit-shadow:0 1px 3px 0 #d4d9e1;--docsearch-key-gradient:linear-gradient(-225deg,#d5dbe4,#f8f8f8);--docsearch-key-shadow:inset 0 -2px 0 0 #cdcde6,inset 0 0 1px 1px #fff,0 1px 2px 1px #1e235a66;--docsearch-footer-height:44px;--docsearch-footer-background:#fff;--docsearch-footer-shadow:0 -1px 0 0 #e0e3e8,0 -3px 6px 0 #45629b1f;--docsearch-primary-color:var(--ifm-color-primary);--docsearch-text-color:var(--ifm-font-color-base);--auth-pills-discord:#d3d6f2;--auth-pills-color:#333;--auth-pills-email:#e0f2fe;--auth-pills-github:#f1f5f9;--auth-pills-google:#ecfccb;--auth-pills-keycloak:#d0ebf5;--auth-pills-username-and-pass:#fce7f3;--docusaurus-tag-list-border:var(--ifm-color-emphasis-300)}:root[data-theme=dark]{--custom-background-color-diff:#2a2a2a;--custom-blog-list-background-color:var(--ifm-background-color);--custom-blog-card-timestamp-color:#a3a3a3;--custom-blog-card-background-color:#000;--docusaurus-highlighted-code-line-bg:#dee6ed;--ifm-menu-color:var(--ifm-color-gray-200);--auth-pills-discord:#2f3670;--auth-pills-color:#fff;--auth-pills-email:#0c4a6e;--auth-pills-github:#334155;--auth-pills-google:#365314;--auth-pills-keycloak:#2d5866;--auth-pills-username-and-pass:#831843}.menu__link:not(.menu__link--active),.menu__list-item-collapsible{background:initial!important}.menu__link:focus:not(.menu__link--active):not(.menu__link--sublist),.menu__link:hover:not(.menu__link--active):not(.menu__link--sublist),.token.namespace{opacity:.7}.theme-doc-sidebar-item-category-level-1,.theme-doc-sidebar-item-link-level-1{margin-bottom:var(--sidebar-item-level-1-spacing)}.theme-doc-sidebar-item-category-level-1>.menu__list-item-collapsible>.menu__link,.theme-doc-sidebar-item-link-level-1>.menu__link{color:var(--sidebar-item-level-1-color);font-weight:700}.navbar__item:has(.navbar-item-docs-version-dropdown:not(.active)){display:none}.video-container{margin-bottom:1.5rem;padding-bottom:56.25%;position:relative;width:100%}.video-container iframe{border:0;height:100%;left:0;position:absolute;top:0;width:100%}.placeholder\:text-neutral-400::placeholder{--tw-text-opacity:1!important;color:rgb(163 163 163/var(--tw-text-opacity))!important}.hover\:border-neutral-400:hover{border-color:rgb(163 163 163/var(--tw-border-opacity))!important}.hover\:border-yellow-400:hover{border-color:rgb(250 204 21/var(--tw-border-opacity))!important}.hover\:bg-gray-100:hover{background-color:rgb(243 244 246/var(--tw-bg-opacity))!important}.hover\:bg-gray-50:hover{background-color:rgb(249 250 251/var(--tw-bg-opacity))!important}.hover\:bg-neutral-200:hover{background-color:rgb(229 229 229/var(--tw-bg-opacity))!important}.hover\:bg-yellow-400:hover{background-color:rgb(250 204 21/var(--tw-bg-opacity))!important}.hover\:bg-yellow-500\/10:hover{background-color:#eab3081a!important}.hover\:text-neutral-400:hover{color:rgb(163 163 163/var(--tw-text-opacity))!important}.hover\:opacity-75:hover{opacity:.75!important}.hover\:shadow-lg:hover{--tw-shadow:0 10px 15px -3px #0000001a,0 4px 6px -4px #0000001a!important}.focus\:outline-none:focus{outline:#0000 solid 2px!important;outline-offset:2px!important}.focus\:ring-2:focus{--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color)!important;box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow,0 0 #0000)!important}.focus\:ring-inset:focus{--tw-ring-inset:inset!important}.focus\:ring-yellow-400:focus{--tw-ring-opacity:1!important;--tw-ring-color:rgb(250 204 21/var(--tw-ring-opacity))!important}.focus\:ring-yellow-500:focus{--tw-ring-opacity:1!important;--tw-ring-color:rgb(234 179 8/var(--tw-ring-opacity))!important}.group:hover .group-hover\:ml-0\.5{margin-left:.125rem!important}.group:hover .group-hover\:h-4{height:1rem!important}.group:hover .group-hover\:w-4{width:1rem!important}body:not(.navigation-with-keyboard) :not(input):focus{outline:0}#docusaurus-base-url-issue-banner-container,.docSidebarContainer_b6E3,.sidebarLogo_isFc,.themedImage_ToTc,[data-theme=dark] .lightToggleIcon_pyhR,[data-theme=light] .darkToggleIcon_wfgR,[hidden],html[data-announcement-bar-initially-dismissed=true] .announcementBar_mb4j{display:none}.skipToContent_fXgn{background-color:var(--ifm-background-surface-color);color:var(--ifm-color-emphasis-900);left:100%;padding:calc(var(--ifm-global-spacing)/2) var(--ifm-global-spacing);position:fixed;top:1rem;z-index:calc(var(--ifm-z-index-fixed) + 1)}.skipToContent_fXgn:focus{box-shadow:var(--ifm-global-shadow-md);left:1rem}.closeButton_CVFx{line-height:0;padding:0}.content_knG7{font-size:85%;padding:5px 0;text-align:center}.content_knG7 a{color:inherit}.announcementBar_mb4j{align-items:center;background-color:var(--ifm-color-white);border-bottom:1px solid var(--ifm-color-emphasis-100);color:var(--ifm-color-black);display:flex;height:var(--docusaurus-announcement-bar-height)}.announcementBarPlaceholder_vyr4{flex:0 0 10px}.announcementBarClose_gvF7{align-self:stretch;flex:0 0 30px}.toggle_vylO{height:2rem;width:2rem}.toggleButton_gllP{align-items:center;border-radius:50%;display:flex;height:100%;justify-content:center;transition:background var(--ifm-transition-fast);width:100%}.toggleButton_gllP:hover{background:var(--ifm-color-emphasis-200)}.toggleButtonDisabled_aARS{cursor:not-allowed}.darkNavbarColorModeToggle_X3D1:hover{background:var(--ifm-color-gray-800)}[data-theme=dark] .themedImage--dark_i4oU,[data-theme=light] .themedImage--light_HNdA{display:initial}.iconExternalLink_nPIU{margin-left:.3rem}.iconLanguage_nlXk{margin-right:5px;vertical-align:text-bottom}.navbarHideable_m1mJ{transition:transform var(--ifm-transition-fast) ease}.navbarHidden_jGov{transform:translate3d(0,calc(-100% - 2px),0)}.errorBoundaryError_a6uf{color:red;white-space:pre-wrap}.footerLogoLink_BH7S{opacity:.5;transition:opacity var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.footerLogoLink_BH7S:hover,.hash-link:focus,:hover>.hash-link{opacity:1}body,html{height:100%;margin:0;padding:0}.mainWrapper_z2l0{display:flex;flex:1 0 auto;flex-direction:column}.docusaurus-mt-lg{margin-top:3rem}#__docusaurus{display:flex;flex-direction:column;min-height:100%}.sidebar_re4s{max-height:calc(100vh - var(--ifm-navbar-height) - 2rem);overflow-y:auto;position:sticky;top:calc(var(--ifm-navbar-height) + 2rem)}.sidebarItemTitle_pO2u{font-size:var(--ifm-h3-font-size);font-weight:var(--ifm-font-weight-bold)}.container_mt6G,.sidebarItemList_Yudw{font-size:.9rem}.sidebarItem__DBe{margin-top:.7rem}.sidebarItemLink_mo7H{color:var(--ifm-font-color-base);display:block}.sidebarItemLinkActive_I1ZP{color:var(--ifm-color-primary)!important}.searchQueryInput_u2C7,.searchVersionInput_m0Ui{background:var(--docsearch-searchbox-focus-background);border:2px solid var(--ifm-toc-border-color);border-radius:var(--ifm-global-radius);color:var(--docsearch-text-color);font:var(--ifm-font-size-base) var(--ifm-font-family-base);margin-bottom:.5rem;padding:.8rem;transition:border var(--ifm-transition-fast) ease;width:100%}.searchQueryInput_u2C7:focus,.searchVersionInput_m0Ui:focus{border-color:var(--docsearch-primary-color);outline:0}.searchQueryInput_u2C7::placeholder{color:var(--docsearch-muted-color)}.searchResultsColumn_JPFH{font-size:.9rem;font-weight:700}.algoliaLogo_rT1R{max-width:150px}.algoliaLogoPathFill_WdUC{fill:var(--ifm-font-color-base)}.searchResultItem_Tv2o{border-bottom:1px solid var(--ifm-toc-border-color);padding:1rem 0}.searchResultItemHeading_KbCB{font-weight:400;margin-bottom:0}.searchResultItemPath_lhe1{--ifm-breadcrumb-separator-size-multiplier:1;color:var(--ifm-color-content-secondary);font-size:.8rem}.searchResultItemSummary_AEaO{font-style:italic;margin:.5rem 0 0}.loadingSpinner_XVxU{animation:1s linear infinite a;border:.4em solid #eee;border-radius:50%;border-top:.4em solid var(--ifm-color-primary);height:3rem;margin:0 auto;width:3rem}@keyframes a{to{transform:rotate(1turn)}}.loader_vvXV{margin-top:2rem}.search-result-match{background:#ffd78e40;color:var(--docsearch-hit-color);padding:.09em 0}.backToTopButton_sjWU{background-color:var(--ifm-color-emphasis-200);border-radius:50%;bottom:1.3rem;box-shadow:var(--ifm-global-shadow-lw);height:3rem;opacity:0;position:fixed;right:1.3rem;transform:scale(0);transition:all var(--ifm-transition-fast) var(--ifm-transition-timing-default);visibility:hidden;width:3rem;z-index:calc(var(--ifm-z-index-fixed) - 1)}.backToTopButton_sjWU:after{background-color:var(--ifm-color-emphasis-1000);content:" ";display:inline-block;height:100%;-webkit-mask:var(--ifm-menu-link-sublist-icon) 50%/2rem 2rem no-repeat;mask:var(--ifm-menu-link-sublist-icon) 50%/2rem 2rem no-repeat;width:100%}.backToTopButtonShow_xfvO{opacity:1;transform:scale(1);visibility:visible}[data-theme=dark]:root{--docusaurus-collapse-button-bg:#ffffff0d;--docusaurus-collapse-button-bg-hover:#ffffff1a}.collapseSidebarButton_PEFL{display:none;margin:0}.docMainContainer_gTbr,.docPage__5DB{display:flex;width:100%}.docPage__5DB{flex:1 0}.docsWrapper_BCFX{display:flex;flex:1 0 auto}.authorCol_Hf19{flex-grow:1!important;max-width:inherit!important}.imageOnlyAuthorRow_pa_O{display:flex;flex-flow:row wrap}.imageOnlyAuthorCol_G86a{margin-left:.3rem;margin-right:.3rem}.sectionSkewed_JxZg{height:100%;left:0;overflow:hidden;position:relative;top:0;transform:skewY(-2deg);transform-origin:100% 0;width:100%}.sectionSkewedContainer_Xzhg{height:100%;position:absolute;width:100%}.leftLights_to8X:after{left:calc(50% - 1100px);top:-10%}.leftLights_to8X:after,.lightsTwo_Ax_R:after{background:radial-gradient(50% 50% at 50% 50%,#ffd60033 0,#ffa80000 100%);content:"";height:912px;mix-blend-mode:normal;pointer-events:none;position:absolute;width:1200px;will-change:filter}.lightsTwo_Ax_R:after{left:50%;top:0}.gradientBackground_goJV{background-image:linear-gradient(90deg,#d946ef,#fc0)}code[class*=language-],pre[class*=language-]{color:#393a34;direction:ltr;font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-size:.9em;-webkit-hyphens:none;hyphens:none;line-height:1.2em;tab-size:4;text-align:left;white-space:pre;word-break:normal;word-spacing:normal}pre>code[class*=language-]{font-size:1em}code[class*=language-] ::selection,code[class*=language-]::selection,pre[class*=language-] ::selection,pre[class*=language-]::selection{background:#b3d4fc}pre[class*=language-]{background-color:#f6f8fa;overflow:auto}:not(pre)>code[class*=language-]{background:#f8f8f8;border:1px solid #ddd;padding:1px .2em}.token.cdata,.token.comment,.token.doctype,.token.prolog{color:#998;font-style:italic}.token.attr-value,.token.string{color:#e3116c}.token.operator,.token.punctuation{color:#393a34}.language-autohotkey .token.keyword,.language-autohotkey .token.selector,.token.atrule,.token.attr-name,.token.keyword,.token.selector,.token.tag{color:#00009f}.language-autohotkey .token.tag,.token.deleted,.token.function{color:#9a050f}.token.bold,.token.function,.token.important{font-weight:700}div.twLandingPage{background-color:#f5f5f5}pre code{line-height:1.25rem}*,:after,:before{border:0 solid #e5e7eb}:after,:before{--tw-content:""}html{-webkit-font-smoothing:auto;-webkit-text-size-adjust:100%;font-feature-settings:normal;font-family:Inter;line-height:1.5;tab-size:4}body{line-height:inherit;margin:0}.twLandingPage hr{border-top-width:1px;color:inherit;height:0}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}.twLandingPage h1,.twLandingPage h2,.twLandingPage h3,.twLandingPage h4,.twLandingPage h5,.twLandingPage h6{font-size:inherit;font-weight:inherit}.twLandingPage a{color:inherit;text-decoration:inherit}.twLandingPage b,.twLandingPage strong{font-weight:bolder}.twLandingPage code,.twLandingPage kbd,.twLandingPage pre,.twLandingPage samp{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-size:1em}.twLandingPage small{font-size:80%}.twLandingPage sub,.twLandingPage sup{font-size:75%;line-height:0;position:relative;vertical-align:initial}.twLandingPage sub{bottom:-.25em}.twLandingPage sup{top:-.5em}.twLandingPage table{border-collapse:collapse;border-color:inherit;text-indent:0}.twLandingPage button,.twLandingPage input,.twLandingPage optgroup,.twLandingPage select,.twLandingPage textarea{color:inherit;font-family:inherit;font-size:100%;font-weight:inherit;line-height:inherit;margin:0;padding:0}.admonitionHeading_tbUL code,.twLandingPage button,.twLandingPage select{text-transform:none}.twLandingPage [type=button],.twLandingPage [type=reset],.twLandingPage [type=submit],.twLandingPage button{-webkit-appearance:button;background-color:initial;background-image:none}:-moz-focusring{outline:auto}:-moz-ui-invalid{box-shadow:none}progress{vertical-align:initial}::-webkit-inner-spin-button,::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}.twLandingPage summary{display:list-item}.twLandingPage fieldset{margin:0;padding:0}.twLandingPage menu,.twLandingPage ol,.twLandingPage ul{list-style:none;margin:0;padding:0}.twLandingPage textarea{resize:vertical}input::placeholder,textarea::placeholder{color:#9ca3af;opacity:1}[role=button],button{cursor:pointer}:disabled{cursor:default}.twLandingPage audio,.twLandingPage canvas,.twLandingPage embed,.twLandingPage iframe,.twLandingPage img,.twLandingPage object,.twLandingPage svg,.twLandingPage video{display:block;vertical-align:middle}.twLandingPage img,.twLandingPage video{height:auto;max-width:100%}.deployment-methods-grid,.social-auth-grid{grid-gap:.5rem;display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));margin-bottom:1rem}.auth-method-box,.deployment-method-box{border:1px solid var(--ifm-color-emphasis-300);border-radius:var(--ifm-pagination-nav-border-radius);display:flex;flex-direction:column;justify-content:center;padding:1.5rem;transition:.1s ease-in-out}.DocSearch-Button,.DocSearch-Button-Container{align-items:center;display:flex}.auth-method-box:hover,.deployment-method-box:hover{border-color:var(--ifm-pagination-nav-color-hover)}.auth-method-box h3,.deployment-method-box h3{color:var(--ifm-link-color);margin:0}.auth-method-box p,.auth-methods-info,.deployment-method-box p,.deployment-methods-info,.social-auth-info{color:var(--ifm-color-secondary-contrast-foreground)}.DocSearch-Button{background:var(--docsearch-searchbox-background);border:0;border-radius:40px;color:var(--docsearch-muted-color);cursor:pointer;font-weight:500;height:36px;justify-content:space-between;padding:0 8px;-webkit-user-select:none;user-select:none}.DocSearch-Button:active,.DocSearch-Button:focus,.DocSearch-Button:hover{background:var(--docsearch-searchbox-focus-background);box-shadow:var(--docsearch-searchbox-shadow);color:var(--docsearch-text-color);outline:0}.DocSearch-Search-Icon{stroke-width:1.6}.DocSearch-Hit-Tree,.DocSearch-Hit-action,.DocSearch-Hit-icon,.DocSearch-Reset{stroke-width:var(--docsearch-icon-stroke-width)}.DocSearch-Button .DocSearch-Search-Icon{color:var(--docsearch-text-color)}.DocSearch-Button-Placeholder{font-size:1rem;padding:0 12px 0 6px}.DocSearch-Button-Keys{display:flex;min-width:calc(40px + .8em)}.DocSearch-Button-Key{align-items:center;background:var(--docsearch-key-gradient);border:0;border-radius:3px;box-shadow:var(--docsearch-key-shadow);color:var(--docsearch-muted-color);display:flex;height:18px;justify-content:center;margin-right:.4em;padding:0 0 2px;position:relative;top:-1px;width:20px}.DocSearch-Container{background-color:var(--docsearch-container-background);height:100vh;left:0;position:fixed;top:0;width:100vw;z-index:200}.DocSearch-Container a{text-decoration:none}.DocSearch-Link{appearance:none;background:none;border:0;color:var(--docsearch-highlight-color);cursor:pointer;font:inherit;margin:0;padding:0}.DocSearch-Modal{background:var(--docsearch-modal-background);border-radius:6px;box-shadow:var(--docsearch-modal-shadow);flex-direction:column;margin:60px auto auto;max-width:var(--docsearch-modal-width);position:relative}.DocSearch-SearchBar{display:flex;padding:var(--docsearch-spacing) var(--docsearch-spacing) 0}.DocSearch-Form{align-items:center;background:var(--docsearch-searchbox-focus-background);border-radius:4px;box-shadow:var(--docsearch-searchbox-shadow);display:flex;height:var(--docsearch-searchbox-height);margin:0;padding:0 var(--docsearch-spacing);position:relative;width:100%}.DocSearch-Input{appearance:none;background:#0000;border:0;color:var(--docsearch-text-color);flex:1;font:inherit;font-size:1.2em;height:100%;outline:0;padding:0 0 0 8px;width:80%}.DocSearch-Input::placeholder{color:var(--docsearch-muted-color);opacity:1}.DocSearch-Input::-webkit-search-cancel-button,.DocSearch-Input::-webkit-search-decoration,.DocSearch-Input::-webkit-search-results-button,.DocSearch-Input::-webkit-search-results-decoration{display:none}.DocSearch-LoadingIndicator,.DocSearch-MagnifierLabel,.DocSearch-Reset{margin:0;padding:0}.DocSearch-Container--Stalled .DocSearch-LoadingIndicator,.DocSearch-MagnifierLabel,.DocSearch-Reset{align-items:center;color:var(--docsearch-highlight-color);display:flex;justify-content:center}.DocSearch-Cancel,.DocSearch-Container--Stalled .DocSearch-MagnifierLabel,.DocSearch-LoadingIndicator,.DocSearch-Reset[hidden]{display:none}.DocSearch-Reset{animation:.1s ease-in forwards b;appearance:none;background:none;border:0;border-radius:50%;color:var(--docsearch-icon-color);cursor:pointer;padding:2px;right:0}.DocSearch-Help,.DocSearch-HitsFooter,.DocSearch-Label{color:var(--docsearch-muted-color)}.DocSearch-Reset:hover{color:var(--docsearch-highlight-color)}.DocSearch-LoadingIndicator svg,.DocSearch-MagnifierLabel svg{height:24px;width:24px}.DocSearch-Dropdown{max-height:calc(var(--docsearch-modal-height) - var(--docsearch-searchbox-height) - var(--docsearch-spacing) - var(--docsearch-footer-height));min-height:var(--docsearch-spacing);overflow-y:auto;overflow-y:overlay;padding:0 var(--docsearch-spacing);scrollbar-color:var(--docsearch-muted-color) var(--docsearch-modal-background);scrollbar-width:thin}.DocSearch-Dropdown::-webkit-scrollbar{width:12px}.DocSearch-Dropdown::-webkit-scrollbar-track{background:#0000}.DocSearch-Dropdown::-webkit-scrollbar-thumb{background-color:var(--docsearch-muted-color);border:3px solid var(--docsearch-modal-background);border-radius:20px}.DocSearch-Dropdown ul{list-style:none;margin:0;padding:0}.DocSearch-Label{font-size:.75em;line-height:1.6em}.DocSearch-Help{font-size:.9em;margin:0;-webkit-user-select:none;user-select:none}.DocSearch-Title{font-size:1.2em}.DocSearch-Logo a{display:flex}.DocSearch-Logo svg{color:var(--docsearch-logo-color);margin-left:8px}.DocSearch-Hits:last-of-type{margin-bottom:24px}.DocSearch-Hits mark{background:none;color:var(--docsearch-highlight-color)}.DocSearch-HitsFooter{display:flex;font-size:.85em;justify-content:center;margin-bottom:var(--docsearch-spacing);padding:var(--docsearch-spacing)}.DocSearch-HitsFooter a{border-bottom:1px solid;color:inherit}.DocSearch-Hit{border-radius:4px;display:flex;padding-bottom:4px;position:relative}.DocSearch-Hit--deleting{opacity:0;transition:.25s linear}.DocSearch-Hit--favoriting{transform:scale(0);transform-origin:top center;transition:.25s linear .25s}.DocSearch-Hit a{background:var(--docsearch-hit-background);border-radius:4px;box-shadow:var(--docsearch-hit-shadow);display:block;padding-left:var(--docsearch-spacing);width:100%}.DocSearch-Hit-source{background:var(--docsearch-modal-background);color:var(--docsearch-highlight-color);font-size:.85em;font-weight:600;line-height:32px;margin:0 -4px;padding:8px 4px 0;position:sticky;top:0;z-index:10}.DocSearch-Hit-Tree{color:var(--docsearch-muted-color);height:var(--docsearch-hit-height);opacity:.5;width:24px}.DocSearch-Hit[aria-selected=true] a{background-color:var(--docsearch-highlight-color)}.DocSearch-Hit-Container{align-items:center;color:var(--docsearch-hit-color);display:flex;flex-direction:row;height:var(--docsearch-hit-height);padding:0 var(--docsearch-spacing) 0 0}.DocSearch-Hit-icon{height:20px;width:20px}.DocSearch-Hit-action,.DocSearch-Hit-icon{color:var(--docsearch-muted-color)}.DocSearch-Hit-action{align-items:center;display:flex;height:22px;width:22px}.DocSearch-Hit-action svg{display:block;height:18px;width:18px}.DocSearch-Hit-action+.DocSearch-Hit-action{margin-left:6px}.DocSearch-Hit-action-button{appearance:none;background:none;border:0;border-radius:50%;color:inherit;cursor:pointer;padding:2px}svg.DocSearch-Hit-Select-Icon{display:none}.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-Select-Icon,.tocCollapsibleContent_vkbj a{display:block}.DocSearch-Hit-action-button:focus,.DocSearch-Hit-action-button:hover{background:#0003;transition:background-color .1s ease-in}.DocSearch-Hit-action-button:focus path,.DocSearch-Hit-action-button:hover path{fill:#fff}.DocSearch-Hit-content-wrapper{display:flex;flex:1 1 auto;flex-direction:column;font-weight:500;justify-content:center;line-height:1.2em;margin:0 8px;overflow-x:hidden;position:relative;text-overflow:ellipsis;white-space:nowrap;width:80%}.DocSearch-Hit-title{font-size:.9em}.DocSearch-Hit-path{color:var(--docsearch-muted-color);font-size:.75em}.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-Tree,.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-action,.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-icon,.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-path,.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-text,.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-title,.DocSearch-Hit[aria-selected=true] mark{color:var(--docsearch-hit-active-color)!important}.DocSearch-ErrorScreen,.DocSearch-NoResults,.DocSearch-StartScreen{font-size:.9em;margin:0 auto;padding:36px 0;text-align:center;width:80%}.DocSearch-Screen-Icon{color:var(--docsearch-muted-color);padding-bottom:12px}.DocSearch-NoResults-Prefill-List{display:inline-block;padding-bottom:24px;text-align:left}.DocSearch-NoResults-Prefill-List ul{display:inline-block;padding:8px 0 0}.DocSearch-NoResults-Prefill-List li{list-style-position:inside;list-style-type:"» "}.DocSearch-Prefill{appearance:none;background:none;border:0;border-radius:1em;color:var(--docsearch-highlight-color);cursor:pointer;display:inline-block;font-size:1em;font-weight:700;padding:0}.DocSearch-Prefill:focus,.DocSearch-Prefill:hover{outline:0;text-decoration:underline}.DocSearch-Footer{align-items:center;background:var(--docsearch-footer-background);border-radius:0 0 8px 8px;box-shadow:var(--docsearch-footer-shadow);display:flex;flex-direction:row-reverse;flex-shrink:0;height:var(--docsearch-footer-height);justify-content:space-between;padding:0 var(--docsearch-spacing);position:relative;-webkit-user-select:none;user-select:none;width:100%;z-index:300}.DocSearch-Commands li,.DocSearch-Commands-Key{align-items:center;display:flex}.DocSearch-Commands{color:var(--docsearch-muted-color);display:flex;list-style:none;margin:0;padding:0}.DocSearch-Commands li:not(:last-of-type){margin-right:.8em}.DocSearch-Commands-Key{background:var(--docsearch-key-gradient);border:0;border-radius:2px;box-shadow:var(--docsearch-key-shadow);color:var(--docsearch-muted-color);height:18px;justify-content:center;margin-right:.4em;padding:0 0 1px;width:20px}.buttonGroup__atx button,.codeBlockContainer_Ckt0{background:var(--prism-background-color);color:var(--prism-color)}@keyframes b{0%{opacity:0}to{opacity:1}}.DocSearch-Button{margin:0;transition:all var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.DocSearch-Container{z-index:calc(var(--ifm-z-index-fixed) + 1)}.auth-methods-grid{grid-gap:.5rem;display:grid;grid-template-columns:repeat(auto-fit,minmax(350px,1fr));margin-bottom:1rem}.codeBlockContainer_Ckt0{border-radius:var(--ifm-code-border-radius);box-shadow:var(--ifm-global-shadow-lw);margin-bottom:var(--ifm-leading)}.codeBlockContent_biex{border-radius:inherit;direction:ltr;position:relative}.codeBlockTitle_Ktv7{border-bottom:1px solid var(--ifm-color-emphasis-300);border-top-left-radius:inherit;border-top-right-radius:inherit;font-size:var(--ifm-code-font-size);font-weight:500;padding:.75rem var(--ifm-pre-padding)}.codeBlock_bY9V{--ifm-pre-background:var(--prism-background-color);margin:0;padding:0}.codeBlockTitle_Ktv7+.codeBlockContent_biex .codeBlock_bY9V{border-top-left-radius:0;border-top-right-radius:0}.codeBlockLines_e6Vv{float:left;font:inherit;min-width:100%;padding:var(--ifm-pre-padding)}.codeBlockLinesWithNumbering_o6Pm{display:table;padding:var(--ifm-pre-padding) 0}.buttonGroup__atx{column-gap:.2rem;display:flex;position:absolute;right:calc(var(--ifm-pre-padding)/2);top:calc(var(--ifm-pre-padding)/2)}.buttonGroup__atx button{align-items:center;border:1px solid var(--ifm-color-emphasis-300);border-radius:var(--ifm-global-radius);display:flex;line-height:0;opacity:0;padding:.4rem;transition:opacity var(--ifm-transition-fast) ease-in-out}.buttonGroup__atx button:focus-visible,.buttonGroup__atx button:hover{opacity:1!important}.theme-code-block:hover .buttonGroup__atx button{opacity:.4}:where(:root){--docusaurus-highlighted-code-line-bg:#484d5b}:where([data-theme=dark]){--docusaurus-highlighted-code-line-bg:#646464}.theme-code-block-highlighted-line{background-color:var(--docusaurus-highlighted-code-line-bg);display:block;margin:0 calc(var(--ifm-pre-padding)*-1);padding:0 var(--ifm-pre-padding)}.codeLine_lJS_{counter-increment:a;display:table-row}.codeLineNumber_Tfdd{background:var(--ifm-pre-background);display:table-cell;left:0;overflow-wrap:normal;padding:0 var(--ifm-pre-padding);position:sticky;text-align:right;width:1%}.codeLineNumber_Tfdd:before{content:counter(a);opacity:.4}.codeLineContent_feaV{padding-right:var(--ifm-pre-padding)}.iconEdit_Z9Sw{margin-right:.3em;vertical-align:sub}.tag_zVej{border:1px solid var(--docusaurus-tag-list-border);transition:border var(--ifm-transition-fast)}.tag_zVej:hover{--docusaurus-tag-list-border:var(--ifm-link-color);text-decoration:none}.tagRegular_sFm0{border-radius:var(--ifm-global-radius);font-size:90%;padding:.2rem .5rem .3rem}.tagWithCount_h2kH{align-items:center;border-left:0;display:flex;padding:0 .5rem 0 1rem;position:relative}.tagWithCount_h2kH:after,.tagWithCount_h2kH:before{border:1px solid var(--docusaurus-tag-list-border);content:"";position:absolute;top:50%;transition:inherit}.tagWithCount_h2kH:before{border-bottom:0;border-right:0;height:1.18rem;right:100%;transform:translate(50%,-50%) rotate(-45deg);width:1.18rem}.tagWithCount_h2kH:after{border-radius:50%;height:.5rem;left:0;transform:translateY(-50%);width:.5rem}.tagWithCount_h2kH span{background:var(--ifm-color-secondary);border-radius:var(--ifm-global-radius);color:var(--ifm-color-black);font-size:.7rem;line-height:1.2;margin-left:.3rem;padding:.1rem .4rem}.tag_Nnez{display:inline-block;margin:.5rem .5rem 0 1rem}.copyButtonIcons_eSgA{height:1.125rem;position:relative;width:1.125rem}.copyButtonIcon_y97N,.copyButtonSuccessIcon_LjdS{fill:currentColor;height:inherit;left:0;opacity:inherit;position:absolute;top:0;transition:all var(--ifm-transition-fast) ease;width:inherit}.copyButtonSuccessIcon_LjdS{color:#00d600;left:50%;opacity:0;top:50%;transform:translate(-50%,-50%) scale(.33)}.copyButtonCopied_obH4 .copyButtonIcon_y97N{opacity:0;transform:scale(.33)}.copyButtonCopied_obH4 .copyButtonSuccessIcon_LjdS{opacity:1;transform:translate(-50%,-50%) scale(1);transition-delay:75ms}.wordWrapButtonIcon_Bwma{height:1.2rem;width:1.2rem}.tags_jXut{display:inline}.tag_QGVx{display:inline-block;margin:0 .4rem .5rem 0}.lastUpdated_vwxv{font-size:smaller;font-style:italic;margin-top:.2rem}.tocCollapsibleButton_TO0P{align-items:center;display:flex;font-size:inherit;justify-content:space-between;padding:.4rem .8rem;width:100%}.tocCollapsibleButton_TO0P:after{background:var(--ifm-menu-link-sublist-icon) 50% 50%/2rem 2rem no-repeat;content:"";filter:var(--ifm-menu-link-sublist-icon-filter);height:1.25rem;transform:rotate(180deg);transition:transform var(--ifm-transition-fast);width:1.25rem}.tocCollapsibleButtonExpanded_MG3E:after,.tocCollapsibleExpanded_sAul{transform:none}.tocCollapsible_ETCw{background-color:var(--ifm-menu-color-background-active);border-radius:var(--ifm-global-radius);margin:1rem 0}.tocCollapsibleContent_vkbj>ul{border-left:none;border-top:1px solid var(--ifm-color-emphasis-300);font-size:15px;padding:.2rem 0}.tocCollapsibleContent_vkbj ul li{margin:.4rem .8rem}.details_lb9f{--docusaurus-details-summary-arrow-size:0.38rem;--docusaurus-details-transition:transform 200ms ease;--docusaurus-details-decoration-color:grey}.details_lb9f>summary{cursor:pointer;list-style:none;padding-left:1rem;position:relative}.details_lb9f>summary::-webkit-details-marker{display:none}.details_lb9f>summary:before{border-color:#0000 #0000 #0000 var(--docusaurus-details-decoration-color);border-style:solid;border-width:var(--docusaurus-details-summary-arrow-size);content:"";left:0;position:absolute;top:.45rem;transform:rotate(0);transform-origin:calc(var(--docusaurus-details-summary-arrow-size)/2) 50%;transition:var(--docusaurus-details-transition)}.collapsibleContent_i85q{border-top:1px solid var(--docusaurus-details-decoration-color);margin-top:1rem;padding-top:1rem}.details_b_Ee{--docusaurus-details-decoration-color:var(--ifm-alert-border-color);--docusaurus-details-transition:transform var(--ifm-transition-fast) ease;border:1px solid var(--ifm-alert-border-color);margin:0 0 var(--ifm-spacing-vertical)}.anchorWithStickyNavbar_LWe7{scroll-margin-top:calc(var(--ifm-navbar-height) + .5rem)}.anchorWithHideOnScrollNavbar_WYt5{scroll-margin-top:.5rem}.hash-link{opacity:0;padding-left:.5rem;transition:opacity var(--ifm-transition-fast);-webkit-user-select:none;user-select:none}.hash-link:before{content:"#"}.containsTaskList_mC6p{list-style:none}.img_ev3q{height:auto}.admonition_LlT9{margin-bottom:1em}.admonitionHeading_tbUL{font:var(--ifm-heading-font-weight) var(--ifm-h5-font-size)/var(--ifm-heading-line-height) var(--ifm-heading-font-family);margin-bottom:.3rem;text-transform:uppercase}.admonitionIcon_kALy{display:inline-block;margin-right:.4em;vertical-align:middle}.admonitionIcon_kALy svg{fill:var(--ifm-alert-foreground-color);display:inline-block;height:1.6em;width:1.6em}.blogPostFooterDetailsFull_mRVl{flex-direction:column}.tableOfContents_bqdL{max-height:calc(100vh - var(--ifm-navbar-height) - 2rem);overflow-y:auto;position:sticky;top:calc(var(--ifm-navbar-height) + 1rem)}.breadcrumbHomeIcon_YNFT{height:1.1rem;position:relative;top:1px;vertical-align:top;width:1.1rem}.breadcrumbsContainer_Z_bl{--ifm-breadcrumb-size-multiplier:0.8;margin-bottom:.8rem}@media (min-width:640px){.container,.lg\:container{max-width:640px}.sm\:ml-3{margin-left:.75rem!important}.sm\:ml-6{margin-left:1.5rem!important}.sm\:mt-0{margin-top:0!important}.sm\:mt-5{margin-top:1.25rem!important}.sm\:flex{display:flex!important}.sm\:w-full{width:100%!important}.sm\:max-w-md{max-width:28rem!important}.sm\:items-stretch{align-items:stretch!important}.sm\:space-x-4>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0!important;margin-left:calc(1rem*(1 - var(--tw-space-x-reverse)))!important;margin-right:calc(1rem*var(--tw-space-x-reverse))!important}.sm\:px-6{padding-left:1.5rem!important;padding-right:1.5rem!important}}@media (min-width:768px){.container,.lg\:container{max-width:768px}.md\:col-span-6{grid-column:span 6/span 6!important}.md\:-mx-6{margin-left:-1.5rem!important;margin-right:-1.5rem!important}.md\:-mt-12{margin-top:-3rem!important}.md\:-mt-6{margin-top:-1.5rem!important}.md\:mb-0{margin-bottom:0!important}.md\:mt-10{margin-top:2.5rem!important}.md\:mt-28{margin-top:7rem!important}.md\:block{display:block!important}.md\:h-10{height:2.5rem!important}.md\:w-\[180px\]{width:180px!important}.md\:max-w-none{max-width:none!important}.md\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))!important}.md\:grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))!important}.md\:gap-16{gap:4rem!important}.md\:gap-8{gap:2rem!important}.md\:p-12{padding:3rem!important}.md\:p-8{padding:2rem!important}.md\:px-20{padding-left:5rem!important;padding-right:5rem!important}.md\:py-24{padding-bottom:6rem!important;padding-top:6rem!important}.md\:py-36{padding-bottom:9rem!important;padding-top:9rem!important}.md\:pb-0{padding-bottom:0!important}.md\:pr-10{padding-right:2.5rem!important}}@media (min-width:997px){.collapseSidebarButton_PEFL,.expandButton_m80_{background-color:var(--docusaurus-collapse-button-bg)}:root{--docusaurus-announcement-bar-height:30px}.announcementBarClose_gvF7,.announcementBarPlaceholder_vyr4{flex-basis:50px}.searchBox_ZlJk{padding:var(--ifm-navbar-item-padding-vertical) var(--ifm-navbar-item-padding-horizontal)}.collapseSidebarButton_PEFL{border:1px solid var(--ifm-toc-border-color);border-radius:0;bottom:0;display:block!important;height:40px;position:sticky}.collapseSidebarButtonIcon_kv0_{margin-top:4px;transform:rotate(180deg)}.expandButtonIcon_BlDH,[dir=rtl] .collapseSidebarButtonIcon_kv0_{transform:rotate(0)}.collapseSidebarButton_PEFL:focus,.collapseSidebarButton_PEFL:hover,.expandButton_m80_:focus,.expandButton_m80_:hover{background-color:var(--docusaurus-collapse-button-bg-hover)}.menuHtmlItem_M9Kj{padding:var(--ifm-menu-link-padding-vertical) var(--ifm-menu-link-padding-horizontal)}.menu_SIkG{flex-grow:1;padding:.5rem}@supports (scrollbar-gutter:stable){.menu_SIkG{padding:.5rem 0 .5rem .5rem;scrollbar-gutter:stable}}.menuWithAnnouncementBar_GW3s{margin-bottom:var(--docusaurus-announcement-bar-height)}.sidebar_njMd{display:flex;flex-direction:column;height:100%;padding-top:var(--ifm-navbar-height);width:var(--doc-sidebar-width)}.sidebarWithHideableNavbar_wUlq{padding-top:0}.sidebarHidden_VK0M{opacity:0;visibility:hidden}.sidebarLogo_isFc{align-items:center;color:inherit!important;display:flex!important;margin:0 var(--ifm-navbar-padding-horizontal);max-height:var(--ifm-navbar-height);min-height:var(--ifm-navbar-height);text-decoration:none!important}.sidebarLogo_isFc img{height:2rem;margin-right:.5rem}.expandButton_m80_{align-items:center;display:flex;height:100%;justify-content:center;position:absolute;right:0;top:0;transition:background-color var(--ifm-transition-fast) ease;width:100%}[dir=rtl] .expandButtonIcon_BlDH{transform:rotate(180deg)}.docSidebarContainer_b6E3{border-right:1px solid var(--ifm-toc-border-color);clip-path:inset(0);display:block;margin-top:calc(var(--ifm-navbar-height)*-1);transition:width var(--ifm-transition-fast) ease;width:var(--doc-sidebar-width);will-change:width}.docSidebarContainerHidden_b3ry{cursor:pointer;width:var(--doc-sidebar-hidden-width)}.sidebarViewport_Xe31{height:100%;max-height:100vh;position:sticky;top:0}.docMainContainer_gTbr{flex-grow:1;max-width:calc(100% - var(--doc-sidebar-width))}.docMainContainerEnhanced_Uz_u{max-width:calc(100% - var(--doc-sidebar-hidden-width))}.docItemWrapperEnhanced_czyv{max-width:calc(var(--ifm-container-width) + var(--doc-sidebar-width))!important}.lastUpdated_vwxv{text-align:right}.tocMobile_ITEo{display:none}.docItemCol_VOVn{max-width:75%!important}}@media (min-width:1024px){.container{max-width:1024px}@media (min-width:640px){.lg\:container{max-width:640px}}@media (min-width:768px){.lg\:container{max-width:768px}}@media (min-width:1024px){.lg\:container{max-width:1024px}}@media (min-width:1280px){.lg\:container{max-width:1280px}}@media (min-width:1536px){.lg\:container{max-width:1536px}}.lg\:container{width:100%;max-width:1024px}.lg\:top-\[1000px\]{top:1000px!important}.lg\:col-span-4{grid-column:span 4/span 4!important}.lg\:col-span-6{grid-column:span 6/span 6!important}.lg\:col-span-7{grid-column:span 7/span 7!important}.lg\:mt-0{margin-top:0!important}.lg\:mt-5{margin-top:1.25rem!important}.lg\:block{display:block!important}.lg\:inline{display:inline!important}.lg\:flex{display:flex!important}.lg\:grid{display:grid!important}.lg\:hidden{display:none!important}.lg\:w-2\/3{width:66.666667%!important}.lg\:max-w-none{max-width:none!important}.lg\:grid-cols-12{grid-template-columns:repeat(12,minmax(0,1fr))!important}.lg\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))!important}.lg\:grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))!important}.lg\:grid-cols-4{grid-template-columns:repeat(4,minmax(0,1fr))!important}.lg\:justify-between{justify-content:space-between!important}.lg\:gap-12{gap:3rem!important}.lg\:gap-16{gap:4rem!important}.lg\:gap-x-8{column-gap:2rem!important}.lg\:divide-x>:not([hidden])~:not([hidden]){--tw-divide-x-reverse:0!important;border-left-width:calc(1px*(1 - var(--tw-divide-x-reverse)))!important;border-right-width:calc(1px*var(--tw-divide-x-reverse))!important}.lg\:p-16{padding:4rem!important}.lg\:px-16{padding-left:4rem!important;padding-right:4rem!important}.lg\:px-24{padding-left:6rem!important;padding-right:6rem!important}.lg\:px-28{padding-left:7rem!important;padding-right:7rem!important}.lg\:py-24{padding-bottom:6rem!important;padding-top:6rem!important}.lg\:pb-8{padding-bottom:2rem!important}.lg\:pr-16{padding-right:4rem!important}.lg\:text-2xl{font-size:1.5rem!important;line-height:2rem!important}.lg\:text-5xl{font-size:3rem!important;line-height:1!important}.lg\:text-xl{font-size:1.25rem!important;line-height:1.75rem!important}.lg\:leading-tight{line-height:1.25!important}}@media (min-width:1280px){.container,.lg\:container{max-width:1280px}.xl\:col-span-1{grid-column:span 1/span 1!important}.xl\:col-span-2{grid-column:span 2/span 2!important}.xl\:col-span-4{grid-column:span 4/span 4!important}.xl\:col-span-7{grid-column:span 7/span 7!important}.xl\:col-start-6{grid-column-start:6!important}.xl\:ml-8{margin-left:2rem!important}.xl\:mt-0{margin-top:0!important}.xl\:flex{display:flex!important}.xl\:grid{display:grid!important}.xl\:w-0{width:0!important}.xl\:w-3\/5{width:60%!important}.xl\:flex-1{flex:1 1 0%!important}.xl\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))!important}.xl\:grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))!important}.xl\:items-center{align-items:center!important}.xl\:gap-x-16{column-gap:4rem!important}.xl\:gap-x-24{column-gap:6rem!important}.xl\:px-20{padding-left:5rem!important;padding-right:5rem!important}}@media (min-width:1440px){.container{max-width:var(--ifm-container-width-xl)}}@media (min-width:1536px){.container,.lg\:container{max-width:1536px}}@media (max-width:996px){.col{--ifm-col-width:100%;flex-basis:var(--ifm-col-width);margin-left:0}.footer{--ifm-footer-padding-horizontal:0}.colorModeToggle_DEke,.footer__link-separator,.navbar__item,.sidebar_re4s,.tableOfContents_bqdL{display:none}.footer__col{margin-bottom:calc(var(--ifm-spacing-vertical)*3)}.footer__link-item{display:block}.hero{padding-left:0;padding-right:0}.navbar>.container,.navbar>.container-fluid{padding:0}.navbar__toggle{display:inherit}.navbar__search-input{width:9rem}.pills--block,.tabs--block{flex-direction:column}.searchBox_ZlJk{position:absolute;right:var(--ifm-navbar-padding-horizontal)}.docItemContainer_F8PC{padding:0 .3rem}}@media only screen and (max-width:996px){.searchQueryColumn_RTkw,.searchResultsColumn_JPFH{max-width:60%!important}.searchLogoColumn_rJIA,.searchVersionColumn_ypXd{max-width:40%!important}.searchLogoColumn_rJIA{padding-left:0!important}}@media (max-width:768px){.DocSearch-Button-Keys,.DocSearch-Button-Placeholder,.DocSearch-Commands,.DocSearch-Hit-Tree{display:none}:root{--docsearch-spacing:10px;--docsearch-footer-height:40px}.DocSearch-Dropdown{height:100%;max-height:calc(var(--docsearch-vh,1vh)*100 - var(--docsearch-searchbox-height) - var(--docsearch-spacing) - var(--docsearch-footer-height))}.DocSearch-Container{height:100vh;height:-webkit-fill-available;height:calc(var(--docsearch-vh,1vh)*100);position:absolute}.DocSearch-Footer{border-radius:0;bottom:0;position:absolute}.DocSearch-Hit-content-wrapper{display:flex;position:relative;width:80%}.DocSearch-Modal{border-radius:0;box-shadow:none;height:100vh;height:-webkit-fill-available;height:calc(var(--docsearch-vh,1vh)*100);margin:0;max-width:100%;width:100%}.DocSearch-Cancel{appearance:none;background:none;border:0;color:var(--docsearch-highlight-color);cursor:pointer;display:inline-block;flex:none;font:inherit;font-size:1em;font-weight:500;margin-left:var(--docsearch-spacing);outline:0;overflow:hidden;padding:0;-webkit-user-select:none;user-select:none;white-space:nowrap}}@media (max-width:576px){.markdown h1:first-child{--ifm-h1-font-size:2rem}.markdown>h2{--ifm-h2-font-size:1.5rem}.markdown>h3{--ifm-h3-font-size:1.25rem}.title_f1Hy{font-size:2rem}}@media screen and (max-width:576px){.searchQueryColumn_RTkw{max-width:100%!important}.searchVersionColumn_ypXd{max-width:100%!important;padding-left:var(--ifm-spacing-horizontal)!important}}@media (hover:hover){.backToTopButton_sjWU:hover{background-color:var(--ifm-color-emphasis-300)}}@media (pointer:fine){.thin-scrollbar{scrollbar-width:thin}.thin-scrollbar::-webkit-scrollbar{height:var(--ifm-scrollbar-size);width:var(--ifm-scrollbar-size)}.thin-scrollbar::-webkit-scrollbar-track{background:var(--ifm-scrollbar-track-background-color);border-radius:10px}.thin-scrollbar::-webkit-scrollbar-thumb{background:var(--ifm-scrollbar-thumb-background-color);border-radius:10px}.thin-scrollbar::-webkit-scrollbar-thumb:hover{background:var(--ifm-scrollbar-thumb-hover-background-color)}}@media (prefers-reduced-motion:reduce){:root{--ifm-transition-fast:0ms;--ifm-transition-slow:0ms}}@media screen and (prefers-reduced-motion:reduce){.DocSearch-Reset{stroke-width:var(--docsearch-icon-stroke-width);animation:none;appearance:none;background:none;border:0;border-radius:50%;color:var(--docsearch-icon-color);cursor:pointer;right:0}.DocSearch-Hit--deleting,.DocSearch-Hit--favoriting{transition:none}.DocSearch-Hit-action-button:focus,.DocSearch-Hit-action-button:hover{background:#0003;transition:none}}@media print{.announcementBar_mb4j,.footer,.menu,.navbar,.pagination-nav,.table-of-contents,.tocMobile_ITEo{display:none}.tabs{page-break-inside:avoid}.codeBlockLines_e6Vv{white-space:pre-wrap}} \ No newline at end of file diff --git a/assets/css/styles.d1566567.css b/assets/css/styles.d1566567.css deleted file mode 100644 index c05d507f49..0000000000 --- a/assets/css/styles.d1566567.css +++ /dev/null @@ -1 +0,0 @@ -@import url(https://fonts.googleapis.com/css2?family=Inter:wght@100;200;300;400;500;600;700;800;900&display=swap);.col,.container{padding:0 var(--ifm-spacing-horizontal)}.markdown>h2,.markdown>h3,.markdown>h4,.markdown>h5,.markdown>h6{margin-bottom:calc(var(--ifm-heading-vertical-rhythm-bottom)*var(--ifm-leading))}blockquote,pre{margin:0 0 var(--ifm-spacing-vertical)}.breadcrumbs__link,.button{transition-timing-function:var(--ifm-transition-timing-default)}.button,code{vertical-align:middle}.button--outline.button--active,.button--outline:active,.button--outline:hover,:root{--ifm-button-color:var(--ifm-font-color-base-inverse)}.menu__link:hover,a{transition:color var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.navbar--dark,:root{--ifm-navbar-link-hover-color:var(--ifm-color-primary)}.menu,.navbar-sidebar{overflow-x:hidden}:root,html[data-theme=dark]{--ifm-color-emphasis-500:var(--ifm-color-gray-500)}.border-blue-500,.border-fuchsia-600,.border-green-600,.border-neutral-300,.border-neutral-500,.border-yellow-600,.hover\:border-neutral-400:hover,.hover\:border-yellow-400:hover{--tw-border-opacity:1!important}.bg-\[\#F3EDE0\],.bg-\[\#f5f4f0\],.bg-\[\#f5f5f5\],.bg-fuchsia-50,.bg-gray-200,.bg-green-50,.bg-neutral-500,.bg-neutral-700,.bg-slate-50,.bg-white,.bg-yellow-50,.bg-yellow-500,.hover\:bg-gray-100:hover,.hover\:bg-gray-50:hover,.hover\:bg-neutral-200:hover,.hover\:bg-yellow-400:hover{--tw-bg-opacity:1!important}.hover\:text-neutral-400:hover,.hover\:text-neutral-500:hover,.text-blue-500,.text-fuchsia-600,.text-green-600,.text-neutral-400,.text-neutral-500,.text-neutral-600,.text-neutral-700,.text-neutral-800,.text-white,.text-yellow-400,.text-yellow-600{--tw-text-opacity:1!important}pre,table{overflow:auto}.toggleButton_gllP,html{-webkit-tap-highlight-color:transparent}.markdown li,body{word-wrap:break-word}*,.DocSearch-Container,.DocSearch-Container *,:after,:before{box-sizing:border-box}:root{--ifm-color-scheme:light;--ifm-dark-value:10%;--ifm-darker-value:15%;--ifm-darkest-value:30%;--ifm-light-value:15%;--ifm-lighter-value:30%;--ifm-lightest-value:50%;--ifm-contrast-background-value:90%;--ifm-contrast-foreground-value:70%;--ifm-contrast-background-dark-value:70%;--ifm-contrast-foreground-dark-value:90%;--ifm-color-primary:#3578e5;--ifm-color-secondary:#ebedf0;--ifm-color-success:#00a400;--ifm-color-info:#54c7ec;--ifm-color-warning:#ffba00;--ifm-color-danger:#fa383e;--ifm-color-primary-dark:#306cce;--ifm-color-primary-darker:#2d66c3;--ifm-color-primary-darkest:#2554a0;--ifm-color-primary-light:#538ce9;--ifm-color-primary-lighter:#72a1ed;--ifm-color-primary-lightest:#9abcf2;--ifm-color-primary-contrast-background:#ebf2fc;--ifm-color-primary-contrast-foreground:#102445;--ifm-color-secondary-dark:#d4d5d8;--ifm-color-secondary-darker:#c8c9cc;--ifm-color-secondary-darkest:#a4a6a8;--ifm-color-secondary-light:#eef0f2;--ifm-color-secondary-lighter:#f1f2f5;--ifm-color-secondary-lightest:#f5f6f8;--ifm-color-secondary-contrast-background:#fdfdfe;--ifm-color-secondary-contrast-foreground:#474748;--ifm-color-success-dark:#009400;--ifm-color-success-darker:#008b00;--ifm-color-success-darkest:#007300;--ifm-color-success-light:#26b226;--ifm-color-success-lighter:#4dbf4d;--ifm-color-success-lightest:#80d280;--ifm-color-success-contrast-background:#e6f6e6;--ifm-color-success-contrast-foreground:#003100;--ifm-color-info-dark:#4cb3d4;--ifm-color-info-darker:#47a9c9;--ifm-color-info-darkest:#3b8ba5;--ifm-color-info-light:#6ecfef;--ifm-color-info-lighter:#87d8f2;--ifm-color-info-lightest:#aae3f6;--ifm-color-info-contrast-background:#eef9fd;--ifm-color-info-contrast-foreground:#193c47;--ifm-color-warning-dark:#e6a700;--ifm-color-warning-darker:#d99e00;--ifm-color-warning-darkest:#b38200;--ifm-color-warning-light:#ffc426;--ifm-color-warning-lighter:#ffcf4d;--ifm-color-warning-lightest:#ffdd80;--ifm-color-warning-contrast-background:#fff8e6;--ifm-color-warning-contrast-foreground:#4d3800;--ifm-color-danger-dark:#e13238;--ifm-color-danger-darker:#d53035;--ifm-color-danger-darkest:#af272b;--ifm-color-danger-light:#fb565b;--ifm-color-danger-lighter:#fb7478;--ifm-color-danger-lightest:#fd9c9f;--ifm-color-danger-contrast-background:#ffebec;--ifm-color-danger-contrast-foreground:#4b1113;--ifm-color-white:#fff;--ifm-color-black:#000;--ifm-color-gray-0:var(--ifm-color-white);--ifm-color-gray-100:#f5f6f7;--ifm-color-gray-200:#ebedf0;--ifm-color-gray-300:#dadde1;--ifm-color-gray-400:#ccd0d5;--ifm-color-gray-500:#bec3c9;--ifm-color-gray-600:#8d949e;--ifm-color-gray-700:#606770;--ifm-color-gray-800:#444950;--ifm-color-gray-900:#1c1e21;--ifm-color-gray-1000:var(--ifm-color-black);--ifm-color-emphasis-0:var(--ifm-color-gray-0);--ifm-color-emphasis-100:var(--ifm-color-gray-100);--ifm-color-emphasis-200:var(--ifm-color-gray-200);--ifm-color-emphasis-300:var(--ifm-color-gray-300);--ifm-color-emphasis-400:var(--ifm-color-gray-400);--ifm-color-emphasis-600:var(--ifm-color-gray-600);--ifm-color-emphasis-700:var(--ifm-color-gray-700);--ifm-color-emphasis-800:var(--ifm-color-gray-800);--ifm-color-emphasis-900:var(--ifm-color-gray-900);--ifm-color-emphasis-1000:var(--ifm-color-gray-1000);--ifm-color-content:var(--ifm-color-emphasis-900);--ifm-color-content-inverse:var(--ifm-color-emphasis-0);--ifm-color-content-secondary:#525860;--ifm-background-color:#0000;--ifm-background-surface-color:var(--ifm-color-content-inverse);--ifm-global-border-width:1px;--ifm-global-radius:0.4rem;--ifm-hover-overlay:#0000000d;--ifm-font-color-base:var(--ifm-color-content);--ifm-font-color-base-inverse:var(--ifm-color-content-inverse);--ifm-font-color-secondary:var(--ifm-color-content-secondary);--ifm-font-family-base:system-ui,-apple-system,Segoe UI,Roboto,Ubuntu,Cantarell,Noto Sans,sans-serif,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";--ifm-font-family-monospace:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;--ifm-font-size-base:100%;--ifm-font-weight-light:300;--ifm-font-weight-normal:400;--ifm-font-weight-semibold:500;--ifm-font-weight-bold:700;--ifm-font-weight-base:var(--ifm-font-weight-normal);--ifm-line-height-base:1.65;--ifm-global-spacing:1rem;--ifm-spacing-vertical:var(--ifm-global-spacing);--ifm-spacing-horizontal:var(--ifm-global-spacing);--ifm-transition-fast:200ms;--ifm-transition-slow:400ms;--ifm-transition-timing-default:cubic-bezier(0.08,0.52,0.52,1);--ifm-global-shadow-lw:0 1px 2px 0 #0000001a;--ifm-global-shadow-md:0 5px 40px #0003;--ifm-global-shadow-tl:0 12px 28px 0 #0003,0 2px 4px 0 #0000001a;--ifm-z-index-dropdown:100;--ifm-z-index-fixed:200;--ifm-z-index-overlay:400;--ifm-container-width:1140px;--ifm-container-width-xl:1320px;--ifm-code-background:#f6f7f8;--ifm-code-border-radius:var(--ifm-global-radius);--ifm-code-font-size:90%;--ifm-code-padding-horizontal:0.1rem;--ifm-code-padding-vertical:0.1rem;--ifm-pre-background:var(--ifm-code-background);--ifm-pre-border-radius:var(--ifm-code-border-radius);--ifm-pre-color:inherit;--ifm-pre-line-height:1.45;--ifm-pre-padding:1rem;--ifm-heading-color:inherit;--ifm-heading-margin-top:0;--ifm-heading-margin-bottom:var(--ifm-spacing-vertical);--ifm-heading-font-family:var(--ifm-font-family-base);--ifm-heading-font-weight:var(--ifm-font-weight-bold);--ifm-heading-line-height:1.25;--ifm-h1-font-size:2rem;--ifm-h2-font-size:1.5rem;--ifm-h3-font-size:1.25rem;--ifm-h4-font-size:1rem;--ifm-h5-font-size:0.875rem;--ifm-h6-font-size:0.85rem;--ifm-image-alignment-padding:1.25rem;--ifm-leading-desktop:1.25;--ifm-leading:calc(var(--ifm-leading-desktop)*1rem);--ifm-list-left-padding:2rem;--ifm-list-margin:1rem;--ifm-list-item-margin:0.25rem;--ifm-list-paragraph-margin:1rem;--ifm-table-cell-padding:0.75rem;--ifm-table-background:#0000;--ifm-table-stripe-background:#00000008;--ifm-table-border-width:1px;--ifm-table-border-color:var(--ifm-color-emphasis-300);--ifm-table-head-background:inherit;--ifm-table-head-color:inherit;--ifm-table-head-font-weight:var(--ifm-font-weight-bold);--ifm-table-cell-color:inherit;--ifm-link-color:var(--ifm-color-primary);--ifm-link-decoration:none;--ifm-link-hover-color:var(--ifm-link-color);--ifm-link-hover-decoration:underline;--ifm-paragraph-margin-bottom:var(--ifm-leading);--ifm-blockquote-font-size:var(--ifm-font-size-base);--ifm-blockquote-border-left-width:2px;--ifm-blockquote-padding-horizontal:var(--ifm-spacing-horizontal);--ifm-blockquote-padding-vertical:0;--ifm-blockquote-shadow:none;--ifm-blockquote-color:var(--ifm-color-emphasis-800);--ifm-blockquote-border-color:var(--ifm-color-emphasis-300);--ifm-hr-background-color:var(--ifm-color-emphasis-500);--ifm-hr-height:1px;--ifm-hr-margin-vertical:1.5rem;--ifm-scrollbar-size:7px;--ifm-scrollbar-track-background-color:#f1f1f1;--ifm-scrollbar-thumb-background-color:silver;--ifm-scrollbar-thumb-hover-background-color:#a7a7a7;--ifm-alert-background-color:inherit;--ifm-alert-border-color:inherit;--ifm-alert-border-radius:var(--ifm-global-radius);--ifm-alert-border-width:0px;--ifm-alert-border-left-width:5px;--ifm-alert-color:var(--ifm-font-color-base);--ifm-alert-padding-horizontal:var(--ifm-spacing-horizontal);--ifm-alert-padding-vertical:var(--ifm-spacing-vertical);--ifm-alert-shadow:var(--ifm-global-shadow-lw);--ifm-avatar-intro-margin:1rem;--ifm-avatar-intro-alignment:inherit;--ifm-avatar-photo-size:3rem;--ifm-badge-background-color:inherit;--ifm-badge-border-color:inherit;--ifm-badge-border-radius:var(--ifm-global-radius);--ifm-badge-border-width:var(--ifm-global-border-width);--ifm-badge-color:var(--ifm-color-white);--ifm-badge-padding-horizontal:calc(var(--ifm-spacing-horizontal)*0.5);--ifm-badge-padding-vertical:calc(var(--ifm-spacing-vertical)*0.25);--ifm-breadcrumb-border-radius:1.5rem;--ifm-breadcrumb-spacing:0.5rem;--ifm-breadcrumb-color-active:var(--ifm-color-primary);--ifm-breadcrumb-item-background-active:var(--ifm-hover-overlay);--ifm-breadcrumb-padding-horizontal:0.8rem;--ifm-breadcrumb-padding-vertical:0.4rem;--ifm-breadcrumb-size-multiplier:1;--ifm-breadcrumb-separator:url('data:image/svg+xml;utf8,');--ifm-breadcrumb-separator-filter:none;--ifm-breadcrumb-separator-size:0.5rem;--ifm-breadcrumb-separator-size-multiplier:1.25;--ifm-button-background-color:inherit;--ifm-button-border-color:var(--ifm-button-background-color);--ifm-button-border-width:var(--ifm-global-border-width);--ifm-button-font-weight:var(--ifm-font-weight-bold);--ifm-button-padding-horizontal:1.5rem;--ifm-button-padding-vertical:0.375rem;--ifm-button-size-multiplier:1;--ifm-button-transition-duration:var(--ifm-transition-fast);--ifm-button-border-radius:calc(var(--ifm-global-radius)*var(--ifm-button-size-multiplier));--ifm-button-group-spacing:2px;--ifm-card-background-color:var(--ifm-background-surface-color);--ifm-card-border-radius:calc(var(--ifm-global-radius)*2);--ifm-card-horizontal-spacing:var(--ifm-global-spacing);--ifm-card-vertical-spacing:var(--ifm-global-spacing);--ifm-toc-border-color:var(--ifm-color-emphasis-300);--ifm-toc-link-color:var(--ifm-color-content-secondary);--ifm-toc-padding-vertical:0.5rem;--ifm-toc-padding-horizontal:0.5rem;--ifm-dropdown-background-color:var(--ifm-background-surface-color);--ifm-dropdown-font-weight:var(--ifm-font-weight-semibold);--ifm-dropdown-link-color:var(--ifm-font-color-base);--ifm-dropdown-hover-background-color:var(--ifm-hover-overlay);--ifm-footer-background-color:var(--ifm-color-emphasis-100);--ifm-footer-color:inherit;--ifm-footer-link-color:var(--ifm-color-emphasis-700);--ifm-footer-link-hover-color:var(--ifm-color-primary);--ifm-footer-link-horizontal-spacing:0.5rem;--ifm-footer-padding-horizontal:calc(var(--ifm-spacing-horizontal)*2);--ifm-footer-padding-vertical:calc(var(--ifm-spacing-vertical)*2);--ifm-footer-title-color:inherit;--ifm-footer-logo-max-width:min(30rem,90vw);--ifm-hero-background-color:var(--ifm-background-surface-color);--ifm-hero-text-color:var(--ifm-color-emphasis-800);--ifm-menu-color:var(--ifm-color-emphasis-700);--ifm-menu-color-active:var(--ifm-color-primary);--ifm-menu-color-background-active:var(--ifm-hover-overlay);--ifm-menu-color-background-hover:var(--ifm-hover-overlay);--ifm-menu-link-padding-horizontal:0.75rem;--ifm-menu-link-padding-vertical:0.375rem;--ifm-menu-link-sublist-icon:url('data:image/svg+xml;utf8,');--ifm-menu-link-sublist-icon-filter:none;--ifm-navbar-background-color:var(--ifm-background-surface-color);--ifm-navbar-height:3.75rem;--ifm-navbar-item-padding-horizontal:0.75rem;--ifm-navbar-item-padding-vertical:0.25rem;--ifm-navbar-link-color:var(--ifm-font-color-base);--ifm-navbar-link-active-color:var(--ifm-link-color);--ifm-navbar-padding-horizontal:var(--ifm-spacing-horizontal);--ifm-navbar-padding-vertical:calc(var(--ifm-spacing-vertical)*0.5);--ifm-navbar-shadow:var(--ifm-global-shadow-lw);--ifm-navbar-search-input-background-color:var(--ifm-color-emphasis-200);--ifm-navbar-search-input-color:var(--ifm-color-emphasis-800);--ifm-navbar-search-input-placeholder-color:var(--ifm-color-emphasis-500);--ifm-navbar-search-input-icon:url('data:image/svg+xml;utf8,');--ifm-navbar-sidebar-width:83vw;--ifm-pagination-border-radius:var(--ifm-global-radius);--ifm-pagination-color-active:var(--ifm-color-primary);--ifm-pagination-font-size:1rem;--ifm-pagination-item-active-background:var(--ifm-hover-overlay);--ifm-pagination-page-spacing:0.2em;--ifm-pagination-padding-horizontal:calc(var(--ifm-spacing-horizontal)*1);--ifm-pagination-padding-vertical:calc(var(--ifm-spacing-vertical)*0.25);--ifm-pagination-nav-border-radius:var(--ifm-global-radius);--ifm-pagination-nav-color-hover:var(--ifm-color-primary);--ifm-pills-color-active:var(--ifm-color-primary);--ifm-pills-color-background-active:var(--ifm-hover-overlay);--ifm-pills-spacing:0.125rem;--ifm-tabs-color:var(--ifm-font-color-secondary);--ifm-tabs-color-active:var(--ifm-color-primary);--ifm-tabs-color-active-border:var(--ifm-tabs-color-active);--ifm-tabs-padding-horizontal:1rem;--ifm-tabs-padding-vertical:1rem}.markdown>h2,:root{--ifm-h2-font-size:2rem}.badge--danger,.badge--info,.badge--primary,.badge--secondary,.badge--success,.badge--warning{--ifm-badge-border-color:var(--ifm-badge-background-color)}.button--link,.button--outline{--ifm-button-background-color:#0000}html{-webkit-font-smoothing:antialiased;text-size-adjust:100%;background-color:var(--ifm-background-color);color:var(--ifm-font-color-base);color-scheme:var(--ifm-color-scheme);font:var(--ifm-font-size-base)/var(--ifm-line-height-base) var(--ifm-font-family-base);text-rendering:optimizelegibility}iframe{border:0;color-scheme:auto}.container{margin:0 auto;max-width:var(--ifm-container-width)}.container--fluid{max-width:inherit}.row{display:flex;flex-wrap:wrap;margin:0 calc(var(--ifm-spacing-horizontal)*-1)}.margin-bottom--none,.margin-vert--none,.markdown>:last-child,.mb-0{margin-bottom:0!important}.margin-top--none,.margin-vert--none,.mt-0,.tabItem_LNqP{margin-top:0!important}.row--no-gutters{margin-left:0;margin-right:0}.margin-horiz--none,.margin-right--none{margin-right:0!important}.row--no-gutters>.col{padding-left:0;padding-right:0}.row--align-top{align-items:flex-start}.row--align-bottom{align-items:flex-end}.menuExternalLink_NmtK,.row--align-center{align-items:center}.row--align-stretch{align-items:stretch}.row--align-baseline{align-items:baseline}.col{--ifm-col-width:100%;flex:1 0;margin-left:0;max-width:var(--ifm-col-width);width:100%}.padding-bottom--none,.padding-vert--none,.py-0{padding-bottom:0!important}.padding-horiz--none,.padding-left--none{padding-left:0!important}.padding-horiz--none,.padding-right--none{padding-right:0!important}.col[class*=col--]{flex:0 0 var(--ifm-col-width)}.col--1{--ifm-col-width:8.33333%}.col--offset-1{margin-left:8.33333%}.col--2{--ifm-col-width:16.66667%}.col--offset-2{margin-left:16.66667%}.col--3{--ifm-col-width:25%}.col--offset-3{margin-left:25%}.col--4{--ifm-col-width:33.33333%}.col--offset-4{margin-left:33.33333%}.col--5{--ifm-col-width:41.66667%}.col--offset-5{margin-left:41.66667%}.col--6{--ifm-col-width:50%}.col--offset-6{margin-left:50%}.col--7{--ifm-col-width:58.33333%}.col--offset-7{margin-left:58.33333%}.col--8{--ifm-col-width:66.66667%}.col--offset-8{margin-left:66.66667%}.col--9{--ifm-col-width:75%}.col--offset-9{margin-left:75%}.col--10{--ifm-col-width:83.33333%}.col--offset-10{margin-left:83.33333%}.col--11{--ifm-col-width:91.66667%}.col--offset-11{margin-left:91.66667%}.col--12{--ifm-col-width:100%}.col--offset-12{margin-left:100%}.group:hover .group-hover\:ml-0,.margin-horiz--none,.margin-left--none{margin-left:0!important}.margin--none{margin:0!important}.margin-bottom--xs,.margin-vert--xs{margin-bottom:.25rem!important}.margin-top--xs,.margin-vert--xs{margin-top:.25rem!important}.margin-horiz--xs,.margin-left--xs,.ml-1{margin-left:.25rem!important}.margin-horiz--xs,.margin-right--xs{margin-right:.25rem!important}.margin--xs{margin:.25rem!important}.margin-bottom--sm,.margin-vert--sm{margin-bottom:.5rem!important}.margin-top--sm,.margin-vert--sm,.mt-2{margin-top:.5rem!important}.margin-horiz--sm,.margin-left--sm,.ml-2,.mx-2{margin-left:.5rem!important}.margin-horiz--sm,.margin-right--sm,.mx-2{margin-right:.5rem!important}.margin--sm{margin:.5rem!important}.margin-bottom--md,.margin-vert--md,.mb-4,.my-4{margin-bottom:1rem!important}.margin-top--md,.margin-vert--md,.mt-4,.my-4{margin-top:1rem!important}.margin-horiz--md,.margin-left--md,.ml-4{margin-left:1rem!important}.margin-horiz--md,.margin-right--md{margin-right:1rem!important}.margin--md{margin:1rem!important}.margin-bottom--lg,.margin-vert--lg,.mb-8{margin-bottom:2rem!important}.margin-top--lg,.margin-vert--lg,.mt-8{margin-top:2rem!important}.margin-horiz--lg,.margin-left--lg{margin-left:2rem!important}.margin-horiz--lg,.margin-right--lg{margin-right:2rem!important}.margin--lg{margin:2rem!important}.margin-bottom--xl,.margin-vert--xl{margin-bottom:5rem!important}.margin-top--xl,.margin-vert--xl,.mt-20{margin-top:5rem!important}.margin-horiz--xl,.margin-left--xl{margin-left:5rem!important}.margin-horiz--xl,.margin-right--xl{margin-right:5rem!important}.margin--xl{margin:5rem!important}.padding--none{padding:0!important}.padding-top--none{padding-top:0!important}.padding-vert--none,.py-0{padding-top:0!important}.padding-bottom--xs,.padding-vert--xs,.py-1{padding-bottom:.25rem!important}.padding-top--xs,.padding-vert--xs,.py-1{padding-top:.25rem!important}.padding-horiz--xs,.padding-left--xs,.px-1{padding-left:.25rem!important}.padding-horiz--xs,.padding-right--xs,.px-1{padding-right:.25rem!important}.padding--xs{padding:.25rem!important}.padding-bottom--sm,.padding-vert--sm,.py-2{padding-bottom:.5rem!important}.padding-top--sm,.padding-vert--sm,.pt-2,.py-2{padding-top:.5rem!important}.padding-horiz--sm,.padding-left--sm,.px-2{padding-left:.5rem!important}.padding-horiz--sm,.padding-right--sm,.px-2{padding-right:.5rem!important}.p-2,.padding--sm{padding:.5rem!important}.padding-bottom--md,.padding-vert--md,.pb-4{padding-bottom:1rem!important}.padding-top--md,.padding-vert--md{padding-top:1rem!important}.padding-horiz--md,.padding-left--md,.pl-4,.px-4{padding-left:1rem!important}.padding-horiz--md,.padding-right--md,.pr-4,.px-4{padding-right:1rem!important}.p-4,.padding--md{padding:1rem!important}.padding-bottom--lg,.padding-vert--lg,.pb-8,.py-8{padding-bottom:2rem!important}.padding-top--lg,.padding-vert--lg,.pt-8,.py-8{padding-top:2rem!important}.padding-horiz--lg,.padding-left--lg{padding-left:2rem!important}.padding-horiz--lg,.padding-right--lg{padding-right:2rem!important}.p-8,.padding--lg{padding:2rem!important}.padding-bottom--xl,.padding-vert--xl,.pb-20,.py-20{padding-bottom:5rem!important}.padding-top--xl,.padding-vert--xl,.py-20{padding-top:5rem!important}.padding-horiz--xl,.padding-left--xl{padding-left:5rem!important}.padding-horiz--xl,.padding-right--xl{padding-right:5rem!important}.padding--xl{padding:5rem!important}code{background-color:var(--ifm-code-background);border:.1rem solid #0000001a;border-radius:var(--ifm-code-border-radius);font-family:var(--ifm-font-family-monospace);font-size:var(--ifm-code-font-size);padding:var(--ifm-code-padding-vertical) var(--ifm-code-padding-horizontal)}a code{color:inherit}pre{background-color:var(--ifm-pre-background);border-radius:var(--ifm-pre-border-radius);color:var(--ifm-pre-color);font:var(--ifm-code-font-size)/var(--ifm-pre-line-height) var(--ifm-font-family-monospace);padding:var(--ifm-pre-padding)}pre code{background-color:initial;border:none;font-size:100%;padding:0}kbd{background-color:var(--ifm-color-emphasis-0);border:1px solid var(--ifm-color-emphasis-400);border-radius:.2rem;box-shadow:inset 0 -1px 0 var(--ifm-color-emphasis-400);color:var(--ifm-color-emphasis-800);font:80% var(--ifm-font-family-monospace);padding:.15rem .3rem}h1,h2,h3,h4,h5,h6{color:var(--ifm-heading-color);font-family:var(--ifm-heading-font-family);font-weight:var(--ifm-heading-font-weight);line-height:var(--ifm-heading-line-height);margin:var(--ifm-heading-margin-top) 0 var(--ifm-heading-margin-bottom) 0}h1{font-size:var(--ifm-h1-font-size)}h2{font-size:var(--ifm-h2-font-size)}h3{font-size:var(--ifm-h3-font-size)}h4{font-size:var(--ifm-h4-font-size)}h5{font-size:var(--ifm-h5-font-size)}h6{font-size:var(--ifm-h6-font-size)}img{max-width:100%}img[align=right]{padding-left:var(--image-alignment-padding)}img[align=left]{padding-right:var(--image-alignment-padding)}.markdown{--ifm-h1-vertical-rhythm-top:3;--ifm-h2-vertical-rhythm-top:2;--ifm-h3-vertical-rhythm-top:1.5;--ifm-heading-vertical-rhythm-top:1.25;--ifm-h1-vertical-rhythm-bottom:1.25;--ifm-heading-vertical-rhythm-bottom:1}.markdown:after,.markdown:before{content:"";display:table}.markdown:after{clear:both}.markdown h1:first-child{--ifm-h1-font-size:3rem;margin-bottom:calc(var(--ifm-h1-vertical-rhythm-bottom)*var(--ifm-leading))}.markdown>h2{margin-top:calc(var(--ifm-h2-vertical-rhythm-top)*var(--ifm-leading))}.markdown>h3{--ifm-h3-font-size:1.5rem;margin-top:calc(var(--ifm-h3-vertical-rhythm-top)*var(--ifm-leading))}.markdown>h4,.markdown>h5,.markdown>h6{margin-top:calc(var(--ifm-heading-vertical-rhythm-top)*var(--ifm-leading))}.markdown>p,.markdown>pre,.markdown>ul,.tabList__CuJ{margin-bottom:var(--ifm-leading)}.markdown li>p{margin-top:var(--ifm-list-paragraph-margin)}.markdown li+li{margin-top:var(--ifm-list-item-margin)}ol,ul{margin:0 0 var(--ifm-list-margin);padding-left:var(--ifm-list-left-padding)}ol ol,ul ol{list-style-type:lower-roman}ol ol,ol ul,ul ol,ul ul{margin:0}ol ol ol,ol ul ol,ul ol ol,ul ul ol{list-style-type:lower-alpha}table{border-collapse:collapse;display:block;margin-bottom:var(--ifm-spacing-vertical)}table thead tr{border-bottom:2px solid var(--ifm-table-border-color)}table thead,table tr:nth-child(2n){background-color:var(--ifm-table-stripe-background)}table tr{background-color:var(--ifm-table-background);border-top:var(--ifm-table-border-width) solid var(--ifm-table-border-color)}table td,table th{border:var(--ifm-table-border-width) solid var(--ifm-table-border-color);padding:var(--ifm-table-cell-padding)}table th{background-color:var(--ifm-table-head-background);color:var(--ifm-table-head-color);font-weight:var(--ifm-table-head-font-weight)}table td{color:var(--ifm-table-cell-color)}strong{font-weight:var(--ifm-font-weight-bold)}a{color:var(--ifm-link-color);text-decoration:var(--ifm-link-decoration)}a:hover{color:var(--ifm-link-hover-color);text-decoration:var(--ifm-link-hover-decoration)}.button:hover,.text--no-decoration,.text--no-decoration:hover,a:not([href]){text-decoration:none}p{margin:0 0 var(--ifm-paragraph-margin-bottom)}blockquote{border-left:var(--ifm-blockquote-border-left-width) solid var(--ifm-blockquote-border-color);box-shadow:var(--ifm-blockquote-shadow);color:var(--ifm-blockquote-color);font-size:var(--ifm-blockquote-font-size);padding:var(--ifm-blockquote-padding-vertical) var(--ifm-blockquote-padding-horizontal)}blockquote>:first-child{margin-top:0}blockquote>:last-child{margin-bottom:0}hr{background-color:var(--ifm-hr-background-color);border:0;height:var(--ifm-hr-height);margin:var(--ifm-hr-margin-vertical) 0}.shadow--lw{box-shadow:var(--ifm-global-shadow-lw)!important}.shadow--md{box-shadow:var(--ifm-global-shadow-md)!important}.shadow--tl{box-shadow:var(--ifm-global-shadow-tl)!important}.text--primary,.wordWrapButtonEnabled_EoeP .wordWrapButtonIcon_Bwma{color:var(--ifm-color-primary)}.text--secondary{color:var(--ifm-color-secondary)}.text--success{color:var(--ifm-color-success)}.text--info{color:var(--ifm-color-info)}.text--warning{color:var(--ifm-color-warning)}.text--danger{color:var(--ifm-color-danger)}.text--center{text-align:center}.text--left{text-align:left}.text--justify{text-align:justify}.text--right{text-align:right}.text--capitalize{text-transform:capitalize}.text--lowercase{text-transform:lowercase}.alert__heading,.text--uppercase{text-transform:uppercase}.text--light{font-weight:var(--ifm-font-weight-light)}.text--normal{font-weight:var(--ifm-font-weight-normal)}.text--semibold{font-weight:var(--ifm-font-weight-semibold)}.text--bold{font-weight:var(--ifm-font-weight-bold)}.text--italic,.token.italic{font-style:italic}.text--truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.text--break{word-wrap:break-word!important;word-break:break-word!important}.clean-btn{background:none;border:none;color:inherit;cursor:pointer;font-family:inherit;padding:0}.alert,.alert .close{color:var(--ifm-alert-foreground-color)}.clean-list{list-style:none;padding-left:0}.alert--primary{--ifm-alert-background-color:var(--ifm-color-primary-contrast-background);--ifm-alert-background-color-highlight:#3578e526;--ifm-alert-foreground-color:var(--ifm-color-primary-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-primary-dark)}.alert--secondary{--ifm-alert-background-color:var(--ifm-color-secondary-contrast-background);--ifm-alert-background-color-highlight:#ebedf026;--ifm-alert-foreground-color:var(--ifm-color-secondary-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-secondary-dark)}.alert--success{--ifm-alert-background-color:var(--ifm-color-success-contrast-background);--ifm-alert-background-color-highlight:#00a40026;--ifm-alert-foreground-color:var(--ifm-color-success-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-success-dark)}.alert--info{--ifm-alert-background-color:var(--ifm-color-info-contrast-background);--ifm-alert-background-color-highlight:#54c7ec26;--ifm-alert-foreground-color:var(--ifm-color-info-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-info-dark)}.alert--warning{--ifm-alert-background-color:var(--ifm-color-warning-contrast-background);--ifm-alert-background-color-highlight:#ffba0026;--ifm-alert-foreground-color:var(--ifm-color-warning-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-warning-dark)}.alert--danger{--ifm-alert-background-color:var(--ifm-color-danger-contrast-background);--ifm-alert-background-color-highlight:#fa383e26;--ifm-alert-foreground-color:var(--ifm-color-danger-contrast-foreground);--ifm-alert-border-color:var(--ifm-color-danger-dark)}.alert{--ifm-code-background:var(--ifm-alert-background-color-highlight);--ifm-link-color:var(--ifm-alert-foreground-color);--ifm-link-hover-color:var(--ifm-alert-foreground-color);--ifm-link-decoration:underline;--ifm-tabs-color:var(--ifm-alert-foreground-color);--ifm-tabs-color-active:var(--ifm-alert-foreground-color);--ifm-tabs-color-active-border:var(--ifm-alert-border-color);background-color:var(--ifm-alert-background-color);border:var(--ifm-alert-border-width) solid var(--ifm-alert-border-color);border-left-width:var(--ifm-alert-border-left-width);border-radius:var(--ifm-alert-border-radius);box-shadow:var(--ifm-alert-shadow);padding:var(--ifm-alert-padding-vertical) var(--ifm-alert-padding-horizontal)}.alert__heading{align-items:center;display:flex;font:700 var(--ifm-h5-font-size)/var(--ifm-heading-line-height) var(--ifm-heading-font-family);margin-bottom:.5rem}.alert__icon{display:inline-flex;margin-right:.4em}.alert__icon svg{fill:var(--ifm-alert-foreground-color);stroke:var(--ifm-alert-foreground-color);stroke-width:0}.alert .close{margin:calc(var(--ifm-alert-padding-vertical)*-1) calc(var(--ifm-alert-padding-horizontal)*-1) 0 0;opacity:.75}.alert .close:focus,.alert .close:hover{opacity:1}.alert a{text-decoration-color:var(--ifm-alert-border-color)}.alert a:hover{text-decoration-thickness:2px}.avatar{column-gap:var(--ifm-avatar-intro-margin);display:flex}.avatar__photo{border-radius:50%;display:block;height:var(--ifm-avatar-photo-size);overflow:hidden;width:var(--ifm-avatar-photo-size)}.card--full-height,.navbar__logo img{height:100%}.avatar__photo--sm{--ifm-avatar-photo-size:2rem}.avatar__photo--lg{--ifm-avatar-photo-size:4rem}.avatar__photo--xl{--ifm-avatar-photo-size:6rem}.avatar__intro{display:flex;flex:1 1;flex-direction:column;justify-content:center;text-align:var(--ifm-avatar-intro-alignment)}.badge,.breadcrumbs__item,.breadcrumbs__link,.button,.dropdown>.navbar__link:after{display:inline-block}.avatar__name{font:700 var(--ifm-h4-font-size)/var(--ifm-heading-line-height) var(--ifm-font-family-base)}.avatar__subtitle{margin-top:.25rem}.avatar--vertical{--ifm-avatar-intro-alignment:center;--ifm-avatar-intro-margin:0.5rem;align-items:center;flex-direction:column}.badge{background-color:var(--ifm-badge-background-color);border:var(--ifm-badge-border-width) solid var(--ifm-badge-border-color);border-radius:var(--ifm-badge-border-radius);color:var(--ifm-badge-color);font-size:75%;font-weight:var(--ifm-font-weight-bold);line-height:1;padding:var(--ifm-badge-padding-vertical) var(--ifm-badge-padding-horizontal)}.badge--primary{--ifm-badge-background-color:var(--ifm-color-primary)}.badge--secondary{--ifm-badge-background-color:var(--ifm-color-secondary);color:var(--ifm-color-black)}.breadcrumbs__link,.button.button--secondary.button--outline:not(.button--active):not(:hover){color:var(--ifm-font-color-base)}.badge--success{--ifm-badge-background-color:var(--ifm-color-success)}.badge--info{--ifm-badge-background-color:var(--ifm-color-info)}.badge--warning{--ifm-badge-background-color:var(--ifm-color-warning)}.badge--danger{--ifm-badge-background-color:var(--ifm-color-danger)}.breadcrumbs{margin-bottom:0;padding-left:0}.breadcrumbs__item:not(:last-child):after{background:var(--ifm-breadcrumb-separator) center;content:" ";display:inline-block;filter:var(--ifm-breadcrumb-separator-filter);height:calc(var(--ifm-breadcrumb-separator-size)*var(--ifm-breadcrumb-size-multiplier)*var(--ifm-breadcrumb-separator-size-multiplier));margin:0 var(--ifm-breadcrumb-spacing);opacity:.5;width:calc(var(--ifm-breadcrumb-separator-size)*var(--ifm-breadcrumb-size-multiplier)*var(--ifm-breadcrumb-separator-size-multiplier))}.breadcrumbs__item--active .breadcrumbs__link{background:var(--ifm-breadcrumb-item-background-active);color:var(--ifm-breadcrumb-color-active)}.breadcrumbs__link{border-radius:var(--ifm-breadcrumb-border-radius);font-size:calc(1rem*var(--ifm-breadcrumb-size-multiplier));padding:calc(var(--ifm-breadcrumb-padding-vertical)*var(--ifm-breadcrumb-size-multiplier)) calc(var(--ifm-breadcrumb-padding-horizontal)*var(--ifm-breadcrumb-size-multiplier));transition-duration:var(--ifm-transition-fast);transition-property:background,color}.breadcrumbs__link:any-link:hover,.breadcrumbs__link:link:hover,.breadcrumbs__link:visited:hover,area[href].breadcrumbs__link:hover{background:var(--ifm-breadcrumb-item-background-active);text-decoration:none}.breadcrumbs--sm{--ifm-breadcrumb-size-multiplier:0.8}.breadcrumbs--lg{--ifm-breadcrumb-size-multiplier:1.2}.button{background-color:var(--ifm-button-background-color);border:var(--ifm-button-border-width) solid var(--ifm-button-border-color);border-radius:var(--ifm-button-border-radius);cursor:pointer;font-size:calc(.875rem*var(--ifm-button-size-multiplier));font-weight:var(--ifm-button-font-weight);line-height:1.5;padding:calc(var(--ifm-button-padding-vertical)*var(--ifm-button-size-multiplier)) calc(var(--ifm-button-padding-horizontal)*var(--ifm-button-size-multiplier));text-align:center;transition-duration:var(--ifm-button-transition-duration);transition-property:color,background,border-color;-webkit-user-select:none;user-select:none;white-space:nowrap}.button,.button:hover{color:var(--ifm-button-color)}.button--outline{--ifm-button-color:var(--ifm-button-border-color)}.button--outline:hover{--ifm-button-background-color:var(--ifm-button-border-color)}.button--link{--ifm-button-border-color:#0000;color:var(--ifm-link-color);text-decoration:var(--ifm-link-decoration)}.button--link.button--active,.button--link:active,.button--link:hover{color:var(--ifm-link-hover-color);text-decoration:var(--ifm-link-hover-decoration)}.button.disabled,.button:disabled,.button[disabled]{opacity:.65;pointer-events:none}.button--sm{--ifm-button-size-multiplier:0.8}.button--lg{--ifm-button-size-multiplier:1.35}.button--block{display:block;width:100%}.button.button--secondary{color:var(--ifm-color-gray-900)}:where(.button--primary){--ifm-button-background-color:var(--ifm-color-primary);--ifm-button-border-color:var(--ifm-color-primary)}:where(.button--primary):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-primary-dark);--ifm-button-border-color:var(--ifm-color-primary-dark)}.button--primary.button--active,.button--primary:active{--ifm-button-background-color:var(--ifm-color-primary-darker);--ifm-button-border-color:var(--ifm-color-primary-darker)}:where(.button--secondary){--ifm-button-background-color:var(--ifm-color-secondary);--ifm-button-border-color:var(--ifm-color-secondary)}:where(.button--secondary):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-secondary-dark);--ifm-button-border-color:var(--ifm-color-secondary-dark)}.button--secondary.button--active,.button--secondary:active{--ifm-button-background-color:var(--ifm-color-secondary-darker);--ifm-button-border-color:var(--ifm-color-secondary-darker)}:where(.button--success){--ifm-button-background-color:var(--ifm-color-success);--ifm-button-border-color:var(--ifm-color-success)}:where(.button--success):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-success-dark);--ifm-button-border-color:var(--ifm-color-success-dark)}.button--success.button--active,.button--success:active{--ifm-button-background-color:var(--ifm-color-success-darker);--ifm-button-border-color:var(--ifm-color-success-darker)}:where(.button--info){--ifm-button-background-color:var(--ifm-color-info);--ifm-button-border-color:var(--ifm-color-info)}:where(.button--info):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-info-dark);--ifm-button-border-color:var(--ifm-color-info-dark)}.button--info.button--active,.button--info:active{--ifm-button-background-color:var(--ifm-color-info-darker);--ifm-button-border-color:var(--ifm-color-info-darker)}:where(.button--warning){--ifm-button-background-color:var(--ifm-color-warning);--ifm-button-border-color:var(--ifm-color-warning)}:where(.button--warning):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-warning-dark);--ifm-button-border-color:var(--ifm-color-warning-dark)}.button--warning.button--active,.button--warning:active{--ifm-button-background-color:var(--ifm-color-warning-darker);--ifm-button-border-color:var(--ifm-color-warning-darker)}:where(.button--danger){--ifm-button-background-color:var(--ifm-color-danger);--ifm-button-border-color:var(--ifm-color-danger)}:where(.button--danger):not(.button--outline):hover{--ifm-button-background-color:var(--ifm-color-danger-dark);--ifm-button-border-color:var(--ifm-color-danger-dark)}.button--danger.button--active,.button--danger:active{--ifm-button-background-color:var(--ifm-color-danger-darker);--ifm-button-border-color:var(--ifm-color-danger-darker)}.button-group{display:inline-flex;gap:var(--ifm-button-group-spacing)}.button-group>.button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}.button-group>.button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0}.button-group--block{display:flex;justify-content:stretch}.button-group--block>.button{flex-grow:1}.card{background-color:var(--ifm-card-background-color);border-radius:var(--ifm-card-border-radius);box-shadow:var(--ifm-global-shadow-lw);display:flex;flex-direction:column;overflow:hidden}.card__image{padding-top:var(--ifm-card-vertical-spacing)}.card__image:first-child{padding-top:0}.card__body,.card__footer,.card__header{padding:var(--ifm-card-vertical-spacing) var(--ifm-card-horizontal-spacing)}.card__body:not(:last-child),.card__footer:not(:last-child),.card__header:not(:last-child){padding-bottom:0}.card__body>:last-child,.card__footer>:last-child,.card__header>:last-child{margin-bottom:0}.card__footer{margin-top:auto}.table-of-contents{font-size:.8rem;margin-bottom:0;padding:var(--ifm-toc-padding-vertical) 0}.table-of-contents,.table-of-contents ul{list-style:none;padding-left:var(--ifm-toc-padding-horizontal)}.table-of-contents li{margin:var(--ifm-toc-padding-vertical) var(--ifm-toc-padding-horizontal)}.table-of-contents__left-border{border-left:1px solid var(--ifm-toc-border-color)}.table-of-contents__link{color:var(--ifm-toc-link-color);display:block}.table-of-contents__link--active,.table-of-contents__link--active code,.table-of-contents__link:hover,.table-of-contents__link:hover code{color:var(--ifm-color-primary);text-decoration:none}.close{color:var(--ifm-color-black);float:right;font-size:1.5rem;font-weight:var(--ifm-font-weight-bold);line-height:1;opacity:.5;padding:1rem;transition:opacity var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.close:hover{opacity:.7}.close:focus,.theme-code-block-highlighted-line .codeLineNumber_Tfdd:before{opacity:.8}.dropdown{display:inline-flex;font-weight:var(--ifm-dropdown-font-weight);position:relative;vertical-align:top}.dropdown--hoverable:hover .dropdown__menu,.dropdown--show .dropdown__menu{opacity:1;pointer-events:all;transform:translateY(-1px);visibility:visible}.dropdown--right .dropdown__menu{left:inherit;right:0}.dropdown--nocaret .navbar__link:after{content:none!important}.dropdown__menu{background-color:var(--ifm-dropdown-background-color);border-radius:var(--ifm-global-radius);box-shadow:var(--ifm-global-shadow-md);left:0;list-style:none;max-height:80vh;min-width:10rem;opacity:0;overflow-y:auto;padding:.5rem;pointer-events:none;position:absolute;top:calc(100% - var(--ifm-navbar-item-padding-vertical) + .3rem);transform:translateY(-.625rem);transition-duration:var(--ifm-transition-fast);transition-property:opacity,transform,visibility;transition-timing-function:var(--ifm-transition-timing-default);visibility:hidden;z-index:var(--ifm-z-index-dropdown)}.menu__caret,.menu__link,.menu__list-item-collapsible{border-radius:.25rem;transition:background var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.dropdown__link{border-radius:.25rem;color:var(--ifm-dropdown-link-color);display:block;font-size:.875rem;margin-top:.2rem;padding:.25rem .5rem;white-space:nowrap}.sr-only,.truncate{white-space:nowrap!important}.dropdown__link--active,.dropdown__link:hover{background-color:var(--ifm-dropdown-hover-background-color);color:var(--ifm-dropdown-link-color);text-decoration:none}.dropdown__link--active,.dropdown__link--active:hover{--ifm-dropdown-link-color:var(--ifm-link-color)}.dropdown>.navbar__link:after{border-color:currentcolor #0000;border-style:solid;border-width:.4em .4em 0;content:"";margin-left:.3em;position:relative;top:2px;transform:translateY(-50%)}.footer{background-color:var(--ifm-footer-background-color);color:var(--ifm-footer-color);padding:var(--ifm-footer-padding-vertical) var(--ifm-footer-padding-horizontal)}.footer--dark{--ifm-footer-background-color:#303846;--ifm-footer-color:var(--ifm-footer-link-color);--ifm-footer-link-color:var(--ifm-color-secondary);--ifm-footer-title-color:var(--ifm-color-white)}.footer__links{margin-bottom:1rem}.footer__link-item{color:var(--ifm-footer-link-color);line-height:2}.footer__link-item:hover{color:var(--ifm-footer-link-hover-color)}.footer__link-separator{margin:0 var(--ifm-footer-link-horizontal-spacing)}.footer__logo{margin-top:1rem;max-width:var(--ifm-footer-logo-max-width)}.footer__title{color:var(--ifm-footer-title-color);font:700 var(--ifm-h4-font-size)/var(--ifm-heading-line-height) var(--ifm-font-family-base);margin-bottom:var(--ifm-heading-margin-bottom)}.menu,.navbar__link{font-weight:var(--ifm-font-weight-semibold)}.docItemContainer_Djhp article>:first-child,.docItemContainer_Djhp header+*,.footer__item{margin-top:0}.admonitionContent_S0QG>:last-child,.collapsibleContent_i85q>:last-child,.footer__items,.tabItem_Ymn6>:last-child{margin-bottom:0}.codeBlockStandalone_MEMb,.twLandingPage legend,[type=checkbox]{padding:0}.hero{align-items:center;background-color:var(--ifm-hero-background-color);color:var(--ifm-hero-text-color);display:flex;padding:4rem 2rem}.hero--primary{--ifm-hero-background-color:var(--ifm-color-primary);--ifm-hero-text-color:var(--ifm-font-color-base-inverse)}.hero--dark{--ifm-hero-background-color:#303846;--ifm-hero-text-color:var(--ifm-color-white)}.hero__title,.title_f1Hy{font-size:3rem}.hero__subtitle{font-size:1.5rem}.menu__list{list-style:none;margin:0;padding-left:0}.menu__caret,.menu__link{padding:var(--ifm-menu-link-padding-vertical) var(--ifm-menu-link-padding-horizontal)}.menu__list .menu__list{flex:0 0 100%;margin-top:.25rem;padding-left:var(--ifm-menu-link-padding-horizontal)}.menu__list-item:not(:first-child){margin-top:.25rem}.menu__list-item--collapsed .menu__list{height:0;overflow:hidden}.details_lb9f[data-collapsed=false].isBrowser_bmU9>summary:before,.details_lb9f[open]:not(.isBrowser_bmU9)>summary:before,.menu__list-item--collapsed .menu__caret:before,.menu__list-item--collapsed .menu__link--sublist:after{transform:rotate(90deg)}.menu__list-item-collapsible{display:flex;flex-wrap:wrap;position:relative}.menu__caret:hover,.menu__link:hover,.menu__list-item-collapsible--active,.menu__list-item-collapsible:hover{background:var(--ifm-menu-color-background-hover)}.menu__list-item-collapsible .menu__link--active,.menu__list-item-collapsible .menu__link:hover{background:none!important}.menu__caret,.menu__link{align-items:center;display:flex}.navbar-sidebar,.navbar-sidebar__backdrop{bottom:0;opacity:0;transition-duration:var(--ifm-transition-fast);transition-timing-function:ease-in-out;visibility:hidden;left:0;top:0}.menu__link{color:var(--ifm-menu-color);flex:1;line-height:1.25}.menu__link:hover{color:var(--ifm-menu-color);text-decoration:none}.menu__caret:before,.menu__link--sublist-caret:after{content:"";height:1.25rem;transform:rotate(180deg);transition:transform var(--ifm-transition-fast) linear;width:1.25rem;filter:var(--ifm-menu-link-sublist-icon-filter)}.menu__link--sublist-caret:after{background:var(--ifm-menu-link-sublist-icon) 50%/2rem 2rem;margin-left:auto;min-width:1.25rem}.menu__link--active,.menu__link--active:hover{color:var(--ifm-menu-color-active)}.navbar__brand,.navbar__link{color:var(--ifm-navbar-link-color)}.menu__link--active:not(.menu__link--sublist){background-color:var(--ifm-menu-color-background-active)}.menu__caret:before{background:var(--ifm-menu-link-sublist-icon) 50%/2rem 2rem}.navbar--dark,html[data-theme=dark]{--ifm-menu-link-sublist-icon-filter:invert(100%) sepia(94%) saturate(17%) hue-rotate(223deg) brightness(104%) contrast(98%)}.navbar{background-color:var(--ifm-navbar-background-color);box-shadow:var(--ifm-navbar-shadow);height:var(--ifm-navbar-height);padding:var(--ifm-navbar-padding-vertical) var(--ifm-navbar-padding-horizontal)}.navbar,.navbar>.container,.navbar>.container-fluid{display:flex}.navbar--fixed-top{position:sticky;top:0;z-index:var(--ifm-z-index-fixed)}.navbar__inner{display:flex;flex-wrap:wrap;justify-content:space-between;width:100%}.navbar__brand{align-items:center;display:flex;margin-right:1rem;min-width:0}.navbar__brand:hover{color:var(--ifm-navbar-link-hover-color);text-decoration:none}.announcementBarContent_xLdY,.navbar__title{flex:1 1 auto}.navbar__toggle{display:none;margin-right:.5rem}.navbar__logo{flex:0 0 auto;height:2rem;margin-right:.5rem}.navbar__items{align-items:center;display:flex;flex:1;min-width:0}.navbar__items--center{flex:0 0 auto}.auth-method-box p,.deployment-method-box p,.navbar__items--center .navbar__brand,.twLandingPage blockquote,.twLandingPage dd,.twLandingPage dl,.twLandingPage figure,.twLandingPage h1,.twLandingPage h2,.twLandingPage h3,.twLandingPage h4,.twLandingPage h5,.twLandingPage h6,.twLandingPage hr,.twLandingPage p,pre{margin:0}.navbar__items--center+.navbar__items--right{flex:1}.navbar__items--right{flex:0 0 auto;justify-content:flex-end}.navbar__items--right>:last-child{padding-right:0}.navbar__item{display:inline-block;padding:var(--ifm-navbar-item-padding-vertical) var(--ifm-navbar-item-padding-horizontal)}#nprogress,.navbar__item.dropdown .navbar__link:not([href]){pointer-events:none}.navbar__link--active,.navbar__link:hover{color:var(--ifm-navbar-link-hover-color);text-decoration:none}.navbar--dark,.navbar--primary{--ifm-menu-color:var(--ifm-color-gray-300);--ifm-navbar-link-color:var(--ifm-color-gray-100);--ifm-navbar-search-input-background-color:#ffffff1a;--ifm-navbar-search-input-placeholder-color:#ffffff80;color:var(--ifm-color-white)}.navbar--dark{--ifm-navbar-background-color:#242526;--ifm-menu-color-background-active:#ffffff0d;--ifm-navbar-search-input-color:var(--ifm-color-white)}.navbar--primary{--ifm-navbar-background-color:var(--ifm-color-primary);--ifm-navbar-link-hover-color:var(--ifm-color-white);--ifm-menu-color-active:var(--ifm-color-white);--ifm-navbar-search-input-color:var(--ifm-color-emphasis-500)}.navbar__search-input{-webkit-appearance:none;appearance:none;background:var(--ifm-navbar-search-input-background-color) var(--ifm-navbar-search-input-icon) no-repeat .75rem center/1rem 1rem;border:none;border-radius:2rem;color:var(--ifm-navbar-search-input-color);cursor:text;display:inline-block;font-size:.9rem;height:2rem;padding:0 .5rem 0 2.25rem;width:12.5rem}.navbar__search-input::placeholder{color:var(--ifm-navbar-search-input-placeholder-color)}.navbar-sidebar{background-color:var(--ifm-navbar-background-color);box-shadow:var(--ifm-global-shadow-md);position:fixed;transform:translate3d(-100%,0,0);transition-property:opacity,visibility,transform;width:var(--ifm-navbar-sidebar-width)}.navbar-sidebar--show .navbar-sidebar,.navbar-sidebar__items{transform:translateZ(0)}.navbar-sidebar--show .navbar-sidebar,.navbar-sidebar--show .navbar-sidebar__backdrop{opacity:1;visibility:visible}.navbar-sidebar__backdrop{background-color:#0009;position:fixed;right:0;transition-property:opacity,visibility}.navbar-sidebar__brand{align-items:center;box-shadow:var(--ifm-navbar-shadow);display:flex;flex:1;height:var(--ifm-navbar-height);padding:var(--ifm-navbar-padding-vertical) var(--ifm-navbar-padding-horizontal)}.hover\:shadow-lg:hover,.shadow-2xl,.shadow-lg,.shadow-sm{box-shadow:var(--tw-ring-offset-shadow,0 0 #0000),var(--tw-ring-shadow,0 0 #0000),var(--tw-shadow)!important}.navbar-sidebar__items{display:flex;height:calc(100% - var(--ifm-navbar-height));transition:transform var(--ifm-transition-fast) ease-in-out}.navbar-sidebar__items--show-secondary{transform:translate3d(calc((var(--ifm-navbar-sidebar-width))*-1),0,0)}.navbar-sidebar__item{flex-shrink:0;padding:.5rem;width:calc(var(--ifm-navbar-sidebar-width))}.navbar-sidebar__back{background:var(--ifm-menu-color-background-active);font-size:15px;font-weight:var(--ifm-button-font-weight);margin:0 0 .2rem -.5rem;padding:.6rem 1.5rem;position:relative;text-align:left;top:-.5rem;width:calc(100% + 1rem)}.navbar-sidebar__close{display:flex;margin-left:auto}.pagination{column-gap:var(--ifm-pagination-page-spacing);display:flex;font-size:var(--ifm-pagination-font-size);padding-left:0}.pagination--sm{--ifm-pagination-font-size:0.8rem;--ifm-pagination-padding-horizontal:0.8rem;--ifm-pagination-padding-vertical:0.2rem}.pagination--lg{--ifm-pagination-font-size:1.2rem;--ifm-pagination-padding-horizontal:1.2rem;--ifm-pagination-padding-vertical:0.3rem}.pagination__item{display:inline-flex}.pagination__item>span{padding:var(--ifm-pagination-padding-vertical)}.pagination__item--active .pagination__link{color:var(--ifm-pagination-color-active)}.pagination__item--active .pagination__link,.pagination__item:not(.pagination__item--active):hover .pagination__link{background:var(--ifm-pagination-item-active-background)}.pagination__item--disabled,.pagination__item[disabled]{opacity:.25;pointer-events:none}.pagination__link{border-radius:var(--ifm-pagination-border-radius);color:var(--ifm-font-color-base);display:inline-block;padding:var(--ifm-pagination-padding-vertical) var(--ifm-pagination-padding-horizontal);transition:background var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.pagination__link:hover,.sidebarItemLink_mo7H:hover,a:hover{text-decoration:none}.pagination-nav{grid-gap:var(--ifm-spacing-horizontal);display:grid;gap:var(--ifm-spacing-horizontal);grid-template-columns:repeat(2,1fr)}.pagination-nav__link{border:1px solid var(--ifm-color-emphasis-300);border-radius:var(--ifm-pagination-nav-border-radius);display:block;height:100%;line-height:var(--ifm-heading-line-height);padding:var(--ifm-global-spacing);transition:border-color var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.pagination-nav__link:hover{border-color:var(--ifm-pagination-nav-color-hover);text-decoration:none}.DocSearch-Hit[aria-selected=true] mark,.content_knG7 a{text-decoration:underline}.pagination-nav__link--next{grid-column:2/3;text-align:right}.pagination-nav__label{font-size:var(--ifm-h4-font-size);font-weight:var(--ifm-heading-font-weight);word-break:break-word}.pagination-nav__link--prev .pagination-nav__label:before{content:"« "}.pagination-nav__link--next .pagination-nav__label:after{content:" »"}.pagination-nav__sublabel{color:var(--ifm-color-content-secondary);font-size:var(--ifm-h5-font-size);font-weight:var(--ifm-font-weight-semibold);margin-bottom:.25rem}.pills__item,.tabs{font-weight:var(--ifm-font-weight-bold)}.pills{display:flex;gap:var(--ifm-pills-spacing);padding-left:0}.pills__item{border-radius:.5rem;cursor:pointer;display:inline-block;padding:.25rem 1rem;transition:background var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.tabs,:not(.containsTaskList_mC6p>li)>.containsTaskList_mC6p{padding-left:0}.pills__item--active{color:var(--ifm-pills-color-active)}.pills__item--active,.pills__item:not(.pills__item--active):hover{background:var(--ifm-pills-color-background-active)}.pills--block{justify-content:stretch}.pills--block .pills__item{flex-grow:1;text-align:center}.tabs{color:var(--ifm-tabs-color);display:flex;margin-bottom:0;overflow-x:auto}.tabs__item{border-bottom:3px solid #0000;border-radius:var(--ifm-global-radius);cursor:pointer;display:inline-flex;padding:var(--ifm-tabs-padding-vertical) var(--ifm-tabs-padding-horizontal);transition:background-color var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.transition,.transition-all,.transition-colors{transition-timing-function:cubic-bezier(.4,0,.2,1)!important}.duration-150,.transition,.transition-all,.transition-colors{transition-duration:.15s!important}.tabs__item--active{border-bottom-color:var(--ifm-tabs-color-active-border);border-bottom-left-radius:0;border-bottom-right-radius:0;color:var(--ifm-tabs-color-active)}.tabs__item:hover{background-color:var(--ifm-hover-overlay)}.tabs--block{justify-content:stretch}.tabs--block .tabs__item{flex-grow:1;justify-content:center}html[data-theme=dark]{--ifm-color-scheme:dark;--ifm-color-emphasis-0:var(--ifm-color-gray-1000);--ifm-color-emphasis-100:var(--ifm-color-gray-900);--ifm-color-emphasis-200:var(--ifm-color-gray-800);--ifm-color-emphasis-300:var(--ifm-color-gray-700);--ifm-color-emphasis-400:var(--ifm-color-gray-600);--ifm-color-emphasis-600:var(--ifm-color-gray-400);--ifm-color-emphasis-700:var(--ifm-color-gray-300);--ifm-color-emphasis-800:var(--ifm-color-gray-200);--ifm-color-emphasis-900:var(--ifm-color-gray-100);--ifm-color-emphasis-1000:var(--ifm-color-gray-0);--ifm-background-color:#1b1b1d;--ifm-background-surface-color:#242526;--ifm-hover-overlay:#ffffff0d;--ifm-color-content:#e3e3e3;--ifm-color-content-secondary:#fff;--ifm-breadcrumb-separator-filter:invert(64%) sepia(11%) saturate(0%) hue-rotate(149deg) brightness(99%) contrast(95%);--ifm-code-background:#ffffff1a;--ifm-scrollbar-track-background-color:#444;--ifm-scrollbar-thumb-background-color:#686868;--ifm-scrollbar-thumb-hover-background-color:#7a7a7a;--ifm-table-stripe-background:#ffffff12;--ifm-toc-border-color:var(--ifm-color-emphasis-200);--ifm-color-primary-contrast-background:#102445;--ifm-color-primary-contrast-foreground:#ebf2fc;--ifm-color-secondary-contrast-background:#474748;--ifm-color-secondary-contrast-foreground:#fdfdfe;--ifm-color-success-contrast-background:#003100;--ifm-color-success-contrast-foreground:#e6f6e6;--ifm-color-info-contrast-background:#193c47;--ifm-color-info-contrast-foreground:#eef9fd;--ifm-color-warning-contrast-background:#4d3800;--ifm-color-warning-contrast-foreground:#fff8e6;--ifm-color-danger-contrast-background:#4b1113;--ifm-color-danger-contrast-foreground:#ffebec;--docsearch-text-color:#f5f6f7;--docsearch-container-background:#090a11cc;--docsearch-modal-background:#15172a;--docsearch-modal-shadow:inset 1px 1px 0 0 #2c2e40,0 3px 8px 0 #000309;--docsearch-searchbox-background:#090a11;--docsearch-searchbox-focus-background:#000;--docsearch-hit-color:#bec3c9;--docsearch-hit-shadow:none;--docsearch-hit-background:#090a11;--docsearch-key-gradient:linear-gradient(-26.5deg,#565872,#31355b);--docsearch-key-shadow:inset 0 -2px 0 0 #282d55,inset 0 0 1px 1px #51577d,0 2px 2px 0 #0304094d;--docsearch-footer-background:#1e2136;--docsearch-footer-shadow:inset 0 1px 0 0 #494c6a80,0 -4px 8px 0 #0003;--docsearch-logo-color:#fff;--docsearch-muted-color:#7f8497}#nprogress .bar{background:var(--docusaurus-progress-bar-color);height:2px;left:0;position:fixed;top:0;width:100%;z-index:1031}#nprogress .peg{box-shadow:0 0 10px var(--docusaurus-progress-bar-color),0 0 5px var(--docusaurus-progress-bar-color);height:100%;opacity:1;position:absolute;right:0;transform:rotate(3deg) translateY(-4px);width:100px}*,::backdrop,:after,:before{--tw-border-spacing-x:0;--tw-border-spacing-y:0;--tw-translate-x:0;--tw-translate-y:0;--tw-rotate:0;--tw-skew-x:0;--tw-skew-y:0;--tw-scale-x:1;--tw-scale-y:1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness:proximity;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:#3b82f680;--tw-ring-offset-shadow:0 0 #0000;--tw-ring-shadow:0 0 #0000;--tw-shadow:0 0 #0000;--tw-shadow-colored:0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: }.focus\:ring-2:focus,.ring-0{--tw-ring-offset-shadow:var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color)!important}.container{width:100%}.sr-only{clip:rect(0,0,0,0)!important;border-width:0!important;height:1px!important;margin:-1px!important;overflow:hidden!important;padding:0!important;position:absolute!important;width:1px!important}.pointer-events-none{pointer-events:none!important}.visible{visibility:visible!important}.static{position:static!important}.fixed{position:fixed!important}.absolute{position:absolute!important}.relative{position:relative!important}.sticky{position:sticky!important}.inset-0{inset:0!important}.-inset-y-0,.inset-y-0{bottom:0!important;top:0!important}.-left-\[50\%\]{left:-50%!important}.left-0{left:0!important}.right-4{right:1rem!important}.top-0{top:0!important}.top-4{top:1rem!important}.top-\[1800px\]{top:1800px!important}.z-10{z-index:10!important}.z-50{z-index:50!important}.col-span-12{grid-column:span 12/span 12!important}.col-span-8{grid-column:span 8/span 8!important}.col-start-3{grid-column-start:3!important}.mx-3{margin-left:.75rem!important;margin-right:.75rem!important}.mx-auto{margin-left:auto!important;margin-right:auto!important}.-mr-2{margin-right:-.5rem!important}.mb-10{margin-bottom:2.5rem!important}.mb-12{margin-bottom:3rem!important}.mb-6{margin-bottom:1.5rem!important}.ml-3{margin-left:.75rem!important}.ml-6{margin-left:1.5rem!important}.mt-16{margin-top:4rem!important}.mt-24{margin-top:6rem!important}.mt-3{margin-top:.75rem!important}.mt-6{margin-top:1.5rem!important}.block{display:block!important}.inline-block{display:inline-block!important}.inline{display:inline!important}.flex{display:flex!important}.inline-flex{display:inline-flex!important}.grid{display:grid!important}.hidden{display:none!important}.h-11{height:2.75rem!important}.h-16{height:4rem!important}.h-2{height:.5rem!important}.h-20{height:5rem!important}.h-28{height:7rem!important}.h-3{height:.75rem!important}.h-40{height:10rem!important}.h-5{height:1.25rem!important}.h-6{height:1.5rem!important}.h-60{height:15rem!important}.h-64{height:16rem!important}.h-8{height:2rem!important}.h-full{height:100%!important}.h-px{height:1px!important}.h-screen{height:100vh!important}.min-h-screen{min-height:100vh!important}.w-11{width:2.75rem!important}.w-2{width:.5rem!important}.w-24{width:6rem!important}.w-3{width:.75rem!important}.w-32{width:8rem!important}.w-5{width:1.25rem!important}.w-6{width:1.5rem!important}.w-8{width:2rem!important}.w-\[200\%\]{width:200%!important}.w-full{width:100%!important}.w-screen{width:100vw!important}.min-w-full{min-width:100%!important}.max-w-3xl{max-width:48rem!important}.max-w-lg{max-width:32rem!important}.flex-1{flex:1 1 0%!important}.flex-shrink-0{flex-shrink:0!important}.translate-x-0{--tw-translate-x:0px!important}.transform,.translate-x-0,.translate-x-5,.translate-y-0,.translate-y-1{transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))!important}.translate-x-5{--tw-translate-x:1.25rem!important}.translate-y-0{--tw-translate-y:0px!important}.translate-y-1{--tw-translate-y:0.25rem!important}.cursor-pointer{cursor:pointer!important}.select-none{-webkit-user-select:none!important;user-select:none!important}.resize{resize:both!important}.appearance-none{-webkit-appearance:none!important;appearance:none!important}.grid-cols-1{grid-template-columns:repeat(1,minmax(0,1fr))!important}.grid-cols-12{grid-template-columns:repeat(12,minmax(0,1fr))!important}.grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))!important}.flex-row{flex-direction:row!important}.flex-col{flex-direction:column!important}.items-start{align-items:flex-start!important}.items-end{align-items:flex-end!important}.items-center{align-items:center!important}.items-stretch{align-items:stretch!important}.justify-center{justify-content:center!important}.justify-between{justify-content:space-between!important}.gap-1{gap:.25rem!important}.gap-2{gap:.5rem!important}.gap-3{gap:.75rem!important}.gap-4{gap:1rem!important}.gap-5{gap:1.25rem!important}.gap-6{gap:1.5rem!important}.gap-8{gap:2rem!important}.gap-y-4{row-gap:1rem!important}.space-x-1>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0!important;margin-left:calc(.25rem*(1 - var(--tw-space-x-reverse)))!important;margin-right:calc(.25rem*var(--tw-space-x-reverse))!important}.space-x-2>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0!important;margin-left:calc(.5rem*(1 - var(--tw-space-x-reverse)))!important;margin-right:calc(.5rem*var(--tw-space-x-reverse))!important}.space-x-3>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0!important;margin-left:calc(.75rem*(1 - var(--tw-space-x-reverse)))!important;margin-right:calc(.75rem*var(--tw-space-x-reverse))!important}.space-x-4>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0!important;margin-left:calc(1rem*(1 - var(--tw-space-x-reverse)))!important;margin-right:calc(1rem*var(--tw-space-x-reverse))!important}.space-y-1>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(.25rem*var(--tw-space-y-reverse))!important;margin-top:calc(.25rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-12>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(3rem*var(--tw-space-y-reverse))!important;margin-top:calc(3rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-16>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(4rem*var(--tw-space-y-reverse))!important;margin-top:calc(4rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-2>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(.5rem*var(--tw-space-y-reverse))!important;margin-top:calc(.5rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-3>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(.75rem*var(--tw-space-y-reverse))!important;margin-top:calc(.75rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-4>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(1rem*var(--tw-space-y-reverse))!important;margin-top:calc(1rem*(1 - var(--tw-space-y-reverse)))!important}.space-y-6>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0!important;margin-bottom:calc(1.5rem*var(--tw-space-y-reverse))!important;margin-top:calc(1.5rem*(1 - var(--tw-space-y-reverse)))!important}.divide-y>:not([hidden])~:not([hidden]){--tw-divide-y-reverse:0!important;border-bottom-width:calc(1px*var(--tw-divide-y-reverse))!important;border-top-width:calc(1px*(1 - var(--tw-divide-y-reverse)))!important}.divide-neutral-300>:not([hidden])~:not([hidden]){--tw-divide-opacity:1!important;border-color:rgb(212 212 212/var(--tw-divide-opacity))!important}.divide-white>:not([hidden])~:not([hidden]){--tw-divide-opacity:1!important;border-color:rgb(255 255 255/var(--tw-divide-opacity))!important}.self-center{align-self:center!important}.self-stretch{align-self:stretch!important}.overflow-auto{overflow:auto!important}.DocSearch--active,.overflow-hidden{overflow:hidden!important}.overflow-y-hidden{overflow-y:hidden!important}.overflow-y-scroll{overflow-y:scroll!important}.truncate{overflow:hidden!important;text-overflow:ellipsis!important}.whitespace-pre-wrap{white-space:pre-wrap!important}.rounded{border-radius:.25rem!important}.rounded-2xl{border-radius:1rem!important}.rounded-full{border-radius:9999px!important}.rounded-lg{border-radius:.5rem!important}.rounded-md{border-radius:.375rem!important}.rounded-xl{border-radius:.75rem!important}.rounded-b-md{border-bottom-left-radius:.375rem!important;border-bottom-right-radius:.375rem!important}.rounded-b-none{border-bottom-left-radius:0!important;border-bottom-right-radius:0!important}.rounded-t-md{border-top-left-radius:.375rem!important;border-top-right-radius:.375rem!important}.rounded-t-none{border-top-left-radius:0!important;border-top-right-radius:0!important}.border{border-width:1px!important}.border-2{border-width:2px!important}.border-b{border-bottom-width:1px!important}.border-b-2{border-bottom-width:2px!important}.border-l{border-left-width:1px!important}.border-r{border-right-width:1px!important}.border-t{border-top-width:1px!important}.border-blue-500{border-color:rgb(59 130 246/var(--tw-border-opacity))!important}.border-fuchsia-600{border-color:rgb(192 38 211/var(--tw-border-opacity))!important}.border-green-600{border-color:rgb(22 163 74/var(--tw-border-opacity))!important}.border-neutral-200\/20{border-color:#e5e5e533!important}.border-neutral-300{border-color:rgb(212 212 212/var(--tw-border-opacity))!important}.border-neutral-500{border-color:rgb(115 115 115/var(--tw-border-opacity))!important}.border-transparent{border-color:#0000!important}.border-yellow-500,.hover\:border-yellow-500:hover{--tw-border-opacity:1!important;border-color:rgb(234 179 8/var(--tw-border-opacity))!important}.border-yellow-500\/25{border-color:#eab30840!important}.border-yellow-500\/75{border-color:#eab308bf!important}.border-yellow-600{border-color:rgb(202 138 4/var(--tw-border-opacity))!important}.border-l-neutral-400\/50{border-left-color:#a3a3a380!important}.bg-\[\#F3EDE0\]{background-color:rgb(243 237 224/var(--tw-bg-opacity))!important}.bg-\[\#f5f4f0\]{background-color:rgb(245 244 240/var(--tw-bg-opacity))!important}.bg-\[\#f5f5f5\]{background-color:rgb(245 245 245/var(--tw-bg-opacity))!important}.bg-\[--custom-blog-card-background-color\]{background-color:var(--custom-blog-card-background-color)!important}.bg-fuchsia-50{background-color:rgb(253 244 255/var(--tw-bg-opacity))!important}.bg-gray-200{background-color:rgb(229 231 235/var(--tw-bg-opacity))!important}.bg-green-50{background-color:rgb(240 253 244/var(--tw-bg-opacity))!important}.bg-neutral-100\/50{background-color:#f5f5f580!important}.bg-neutral-500{background-color:rgb(115 115 115/var(--tw-bg-opacity))!important}.bg-neutral-600,.hover\:bg-neutral-600:hover{--tw-bg-opacity:1!important;background-color:rgb(82 82 82/var(--tw-bg-opacity))!important}.bg-neutral-600\/20{background-color:#52525233!important}.bg-neutral-700{background-color:rgb(64 64 64/var(--tw-bg-opacity))!important}.bg-slate-50{background-color:rgb(248 250 252/var(--tw-bg-opacity))!important}.bg-transparent{background-color:initial!important}.bg-white{background-color:rgb(255 255 255/var(--tw-bg-opacity))!important}.bg-yellow-50{background-color:rgb(254 252 232/var(--tw-bg-opacity))!important}.bg-yellow-500{background-color:rgb(234 179 8/var(--tw-bg-opacity))!important}.bg-yellow-500\/20{background-color:#eab30833!important}.bg-yellow-500\/25{background-color:#eab30840!important}.bg-yellow-500\/5{background-color:#eab3080d!important}.object-cover{object-fit:cover!important}.p-3{padding:.75rem!important}.p-5{padding:1.25rem!important}.p-6{padding:1.5rem!important}.px-2\.5{padding-left:.625rem!important;padding-right:.625rem!important}.px-3{padding-left:.75rem!important;padding-right:.75rem!important}.px-5{padding-left:1.25rem!important;padding-right:1.25rem!important}.px-6{padding-left:1.5rem!important;padding-right:1.5rem!important}.py-0\.5{padding-bottom:.125rem!important;padding-top:.125rem!important}.py-1\.5{padding-bottom:.375rem!important;padding-top:.375rem!important}.py-16{padding-bottom:4rem!important;padding-top:4rem!important}.py-5{padding-bottom:1.25rem!important;padding-top:1.25rem!important}.py-6{padding-bottom:1.5rem!important;padding-top:1.5rem!important}.pb-5{padding-bottom:1.25rem!important}.pb-\[56\.25\%\]{padding-bottom:56.25%!important}.pl-3{padding-left:.75rem!important}.pr-5{padding-right:1.25rem!important}.pt-24{padding-top:6rem!important}.text-left{text-align:left!important}.text-center{text-align:center!important}.text-2xl{font-size:1.5rem!important;line-height:2rem!important}.text-4xl{font-size:2.25rem!important;line-height:2.5rem!important}.text-\[11px\]{font-size:11px!important}.text-base{font-size:1rem!important;line-height:1.5rem!important}.text-lg{font-size:1.125rem!important;line-height:1.75rem!important}.text-sm{font-size:.875rem!important;line-height:1.25rem!important}.text-xl{font-size:1.25rem!important;line-height:1.75rem!important}.leading-4,.text-xs{line-height:1rem!important}.text-xs{font-size:.75rem!important}.font-bold{font-weight:700!important}.font-extrabold{font-weight:800!important}.font-medium{font-weight:500!important}.font-semibold{font-weight:600!important}.uppercase{text-transform:uppercase!important}.leading-6{line-height:1.5rem!important}.leading-tight{line-height:1.25!important}.tracking-wider{letter-spacing:.05em!important}.text-\[--custom-blog-card-timestamp-color\]{color:var(--custom-blog-card-timestamp-color)!important}.text-blue-500{color:rgb(59 130 246/var(--tw-text-opacity))!important}.text-fuchsia-600{color:rgb(192 38 211/var(--tw-text-opacity))!important}.text-green-600{color:rgb(22 163 74/var(--tw-text-opacity))!important}.text-neutral-400{color:rgb(163 163 163/var(--tw-text-opacity))!important}.hover\:text-neutral-500:hover,.text-neutral-500{color:rgb(115 115 115/var(--tw-text-opacity))!important}.text-neutral-600{color:rgb(82 82 82/var(--tw-text-opacity))!important}.text-neutral-700{color:rgb(64 64 64/var(--tw-text-opacity))!important}.text-neutral-800{color:rgb(38 38 38/var(--tw-text-opacity))!important}.text-white{color:rgb(255 255 255/var(--tw-text-opacity))!important}.text-yellow-400{color:rgb(250 204 21/var(--tw-text-opacity))!important}.group:hover .group-hover\:text-yellow-500,.hover\:text-yellow-500:hover,.text-yellow-500{--tw-text-opacity:1!important;color:rgb(234 179 8/var(--tw-text-opacity))!important}.text-yellow-600{color:rgb(202 138 4/var(--tw-text-opacity))!important}.underline{text-decoration-line:underline!important}.decoration-neutral-500{text-decoration-color:#737373!important}.decoration-yellow-500{text-decoration-color:#eab308!important}.decoration-2{text-decoration-thickness:2px!important}.opacity-0{opacity:0!important}.opacity-100,.theme-code-block:hover .copyButtonCopied_obH4{opacity:1!important}.opacity-80{opacity:.8!important}.shadow-2xl{--tw-shadow:0 25px 50px -12px #00000040!important;--tw-shadow-colored:0 25px 50px -12px var(--tw-shadow-color)!important}.hover\:shadow-lg:hover,.shadow-lg{--tw-shadow-colored:0 10px 15px -3px var(--tw-shadow-color),0 4px 6px -4px var(--tw-shadow-color)!important}.shadow-lg{--tw-shadow:0 10px 15px -3px #0000001a,0 4px 6px -4px #0000001a!important}.shadow-sm{--tw-shadow:0 1px 2px 0 #0000000d!important;--tw-shadow-colored:0 1px 2px 0 var(--tw-shadow-color)!important}.hover\:shadow-yellow-500\/25:hover,.shadow-yellow-500\/25{--tw-shadow-color:#eab30840!important;--tw-shadow:var(--tw-shadow-colored)!important}.ring-0{--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(var(--tw-ring-offset-width)) var(--tw-ring-color)!important;box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow,0 0 #0000)!important}.drop-shadow-sm{--tw-drop-shadow:drop-shadow(0 1px 1px #0000000d)!important}.drop-shadow-sm,.filter{filter:var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow)!important}.backdrop-blur-sm{--tw-backdrop-blur:blur(4px)!important;-webkit-backdrop-filter:var(--tw-backdrop-blur) var(--tw-backdrop-brightness) var(--tw-backdrop-contrast) var(--tw-backdrop-grayscale) var(--tw-backdrop-hue-rotate) var(--tw-backdrop-invert) var(--tw-backdrop-opacity) var(--tw-backdrop-saturate) var(--tw-backdrop-sepia)!important;backdrop-filter:var(--tw-backdrop-blur) var(--tw-backdrop-brightness) var(--tw-backdrop-contrast) var(--tw-backdrop-grayscale) var(--tw-backdrop-hue-rotate) var(--tw-backdrop-invert) var(--tw-backdrop-opacity) var(--tw-backdrop-saturate) var(--tw-backdrop-sepia)!important}.transition{transition-property:color,background-color,border-color,text-decoration-color,fill,stroke,opacity,box-shadow,transform,filter,backdrop-filter,-webkit-backdrop-filter!important}.transition-all{transition-property:all!important}.transition-colors{transition-property:color,background-color,border-color,text-decoration-color,fill,stroke!important}.duration-200{transition-duration:.2s!important}.ease-in{transition-timing-function:cubic-bezier(.4,0,1,1)!important}.ease-in-out{transition-timing-function:cubic-bezier(.4,0,.2,1)!important}.ease-out{transition-timing-function:cubic-bezier(0,0,.2,1)!important}.blog-list-page{background-color:var(--custom-blog-list-background-color)}.token.boolean,.token.constant,.token.entity,.token.inserted,.token.number,.token.property,.token.regex,.token.symbol,.token.type-class-name,.token.url,.token.variable{color:#36acaa}.token.annotation{color:#747474!important}:root{--docusaurus-progress-bar-color:var(--ifm-color-primary);--custom-background-color:#fdfdfd;--custom-background-color-diff:#f4f4f4;--custom-shadow-lw:0 3px 5px 0px #0000001a;--custom-border-radius:3px;--custom-border-radius-md:6px;--custom-discord-color:#8a9cff;--custom-wasp-color:#fc0;--ifm-h3-font-size:1.3rem;--custom-blog-list-background-color:#f5f5f5;--custom-blog-card-timestamp-color:#737373;--custom-blog-card-background-color:#fff;--ifm-container-width-xl:1280px;--ifm-font-family-base:"Inter",sans-serif;--ifm-color-primary:#bf9900;--ifm-color-primary-dark:#8a6f04;--ifm-color-primary-darker:#1fa588;--ifm-color-primary-darkest:#1a8870;--ifm-color-primary-light:#46cbae;--ifm-color-primary-lighter:#66d4bd;--ifm-color-primary-lightest:#92e0d0;--ifm-code-font-size:95%;--ifm-code-background-dark:#292d3e;--ifm-global-radius:0;--ifm-button-background-color:var(--custom-background-color);--ifm-button-border-radius:var(--custom-border-radius);--ifm-code-border-radius:var(--custom-border-radius);--ifm-heading-font-weight:600;--ifm-col-spacing-vertical:0.5rem;--docusaurus-highlighted-code-line-bg:#e8edf2;--ifm-menu-color:var(--ifm-color-gray-800);--sidebar-item-level-1-color:var(--ifm-color-primary);--sidebar-item-level-1-spacing:1em;--docusaurus-announcement-bar-height:auto;--docusaurus-collapse-button-bg:#0000;--docusaurus-collapse-button-bg-hover:#0000001a;--doc-sidebar-width:300px;--doc-sidebar-hidden-width:30px;--docsearch-primary-color:#5468ff;--docsearch-text-color:#1c1e21;--docsearch-spacing:12px;--docsearch-icon-stroke-width:1.4;--docsearch-highlight-color:var(--docsearch-primary-color);--docsearch-muted-color:#969faf;--docsearch-container-background:#656c85cc;--docsearch-logo-color:#5468ff;--docsearch-modal-width:560px;--docsearch-modal-height:600px;--docsearch-modal-background:#f5f6f7;--docsearch-modal-shadow:inset 1px 1px 0 0 #ffffff80,0 3px 8px 0 #555a64;--docsearch-searchbox-height:56px;--docsearch-searchbox-background:#ebedf0;--docsearch-searchbox-focus-background:#fff;--docsearch-searchbox-shadow:inset 0 0 0 2px var(--docsearch-primary-color);--docsearch-hit-height:56px;--docsearch-hit-color:#444950;--docsearch-hit-active-color:#fff;--docsearch-hit-background:#fff;--docsearch-hit-shadow:0 1px 3px 0 #d4d9e1;--docsearch-key-gradient:linear-gradient(-225deg,#d5dbe4,#f8f8f8);--docsearch-key-shadow:inset 0 -2px 0 0 #cdcde6,inset 0 0 1px 1px #fff,0 1px 2px 1px #1e235a66;--docsearch-footer-height:44px;--docsearch-footer-background:#fff;--docsearch-footer-shadow:0 -1px 0 0 #e0e3e8,0 -3px 6px 0 #45629b1f;--docsearch-primary-color:var(--ifm-color-primary);--docsearch-text-color:var(--ifm-font-color-base);--auth-pills-discord:#d3d6f2;--auth-pills-color:#333;--auth-pills-email:#e0f2fe;--auth-pills-github:#f1f5f9;--auth-pills-google:#ecfccb;--auth-pills-keycloak:#d0ebf5;--auth-pills-username-and-pass:#fce7f3;--docusaurus-tag-list-border:var(--ifm-color-emphasis-300)}:root[data-theme=dark]{--custom-background-color-diff:#2a2a2a;--custom-blog-list-background-color:var(--ifm-background-color);--custom-blog-card-timestamp-color:#a3a3a3;--custom-blog-card-background-color:#000;--docusaurus-highlighted-code-line-bg:#dee6ed;--ifm-menu-color:var(--ifm-color-gray-200);--auth-pills-discord:#2f3670;--auth-pills-color:#fff;--auth-pills-email:#0c4a6e;--auth-pills-github:#334155;--auth-pills-google:#365314;--auth-pills-keycloak:#2d5866;--auth-pills-username-and-pass:#831843}.menu__link:not(.menu__link--active),.menu__list-item-collapsible{background:initial!important}.menu__link:focus:not(.menu__link--active):not(.menu__link--sublist),.menu__link:hover:not(.menu__link--active):not(.menu__link--sublist),.token.namespace{opacity:.7}.theme-doc-sidebar-item-category-level-1,.theme-doc-sidebar-item-link-level-1{margin-bottom:var(--sidebar-item-level-1-spacing)}.theme-doc-sidebar-item-category-level-1>.menu__list-item-collapsible>.menu__link,.theme-doc-sidebar-item-link-level-1>.menu__link{color:var(--sidebar-item-level-1-color);font-weight:700}.navbar__item:has(.navbar-item-docs-version-dropdown:not(.active)){display:none}.video-container{margin-bottom:1.5rem;padding-bottom:56.25%;position:relative;width:100%}.video-container iframe{border:0;height:100%;left:0;position:absolute;top:0;width:100%}.placeholder\:text-neutral-400::placeholder{--tw-text-opacity:1!important;color:rgb(163 163 163/var(--tw-text-opacity))!important}.hover\:border-neutral-400:hover{border-color:rgb(163 163 163/var(--tw-border-opacity))!important}.hover\:border-yellow-400:hover{border-color:rgb(250 204 21/var(--tw-border-opacity))!important}.hover\:bg-gray-100:hover{background-color:rgb(243 244 246/var(--tw-bg-opacity))!important}.hover\:bg-gray-50:hover{background-color:rgb(249 250 251/var(--tw-bg-opacity))!important}.hover\:bg-neutral-200:hover{background-color:rgb(229 229 229/var(--tw-bg-opacity))!important}.hover\:bg-yellow-400:hover{background-color:rgb(250 204 21/var(--tw-bg-opacity))!important}.hover\:bg-yellow-500\/10:hover{background-color:#eab3081a!important}.hover\:text-neutral-400:hover{color:rgb(163 163 163/var(--tw-text-opacity))!important}.hover\:opacity-75:hover{opacity:.75!important}.hover\:shadow-lg:hover{--tw-shadow:0 10px 15px -3px #0000001a,0 4px 6px -4px #0000001a!important}.focus\:outline-none:focus{outline:#0000 solid 2px!important;outline-offset:2px!important}.focus\:ring-2:focus{--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color)!important;box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow,0 0 #0000)!important}.focus\:ring-inset:focus{--tw-ring-inset:inset!important}.focus\:ring-yellow-400:focus{--tw-ring-opacity:1!important;--tw-ring-color:rgb(250 204 21/var(--tw-ring-opacity))!important}.focus\:ring-yellow-500:focus{--tw-ring-opacity:1!important;--tw-ring-color:rgb(234 179 8/var(--tw-ring-opacity))!important}.group:hover .group-hover\:ml-0\.5{margin-left:.125rem!important}.group:hover .group-hover\:h-4{height:1rem!important}.group:hover .group-hover\:w-4{width:1rem!important}body:not(.navigation-with-keyboard) :not(input):focus{outline:0}#docusaurus-base-url-issue-banner-container,.docSidebarContainer_b6E3,.sidebarLogo_isFc,.themedImage_ToTc,[data-theme=dark] .lightToggleIcon_pyhR,[data-theme=light] .darkToggleIcon_wfgR,[hidden],html[data-announcement-bar-initially-dismissed=true] .announcementBar_mb4j{display:none}.skipToContent_fXgn{background-color:var(--ifm-background-surface-color);color:var(--ifm-color-emphasis-900);left:100%;padding:calc(var(--ifm-global-spacing)/2) var(--ifm-global-spacing);position:fixed;top:1rem;z-index:calc(var(--ifm-z-index-fixed) + 1)}.skipToContent_fXgn:focus{box-shadow:var(--ifm-global-shadow-md);left:1rem}.closeButton_CVFx{line-height:0;padding:0}.content_knG7{font-size:85%;padding:5px 0;text-align:center}.content_knG7 a{color:inherit}.announcementBar_mb4j{align-items:center;background-color:var(--ifm-color-white);border-bottom:1px solid var(--ifm-color-emphasis-100);color:var(--ifm-color-black);display:flex;height:var(--docusaurus-announcement-bar-height)}.announcementBarPlaceholder_vyr4{flex:0 0 10px}.announcementBarClose_gvF7{align-self:stretch;flex:0 0 30px}.toggle_vylO{height:2rem;width:2rem}.toggleButton_gllP{align-items:center;border-radius:50%;display:flex;height:100%;justify-content:center;transition:background var(--ifm-transition-fast);width:100%}.toggleButton_gllP:hover{background:var(--ifm-color-emphasis-200)}.toggleButtonDisabled_aARS{cursor:not-allowed}.darkNavbarColorModeToggle_X3D1:hover{background:var(--ifm-color-gray-800)}[data-theme=dark] .themedImage--dark_i4oU,[data-theme=light] .themedImage--light_HNdA{display:initial}.iconExternalLink_nPIU{margin-left:.3rem}.iconLanguage_nlXk{margin-right:5px;vertical-align:text-bottom}.navbarHideable_m1mJ{transition:transform var(--ifm-transition-fast) ease}.navbarHidden_jGov{transform:translate3d(0,calc(-100% - 2px),0)}.errorBoundaryError_a6uf{color:red;white-space:pre-wrap}.footerLogoLink_BH7S{opacity:.5;transition:opacity var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.footerLogoLink_BH7S:hover,.hash-link:focus,:hover>.hash-link{opacity:1}body,html{height:100%;margin:0;padding:0}.mainWrapper_z2l0{display:flex;flex:1 0 auto;flex-direction:column}.docusaurus-mt-lg{margin-top:3rem}#__docusaurus{display:flex;flex-direction:column;min-height:100%}.sidebar_re4s{max-height:calc(100vh - var(--ifm-navbar-height) - 2rem);overflow-y:auto;position:sticky;top:calc(var(--ifm-navbar-height) + 2rem)}.sidebarItemTitle_pO2u{font-size:var(--ifm-h3-font-size);font-weight:var(--ifm-font-weight-bold)}.container_mt6G,.sidebarItemList_Yudw{font-size:.9rem}.sidebarItem__DBe{margin-top:.7rem}.sidebarItemLink_mo7H{color:var(--ifm-font-color-base);display:block}.sidebarItemLinkActive_I1ZP{color:var(--ifm-color-primary)!important}.searchQueryInput_u2C7,.searchVersionInput_m0Ui{background:var(--docsearch-searchbox-focus-background);border:2px solid var(--ifm-toc-border-color);border-radius:var(--ifm-global-radius);color:var(--docsearch-text-color);font:var(--ifm-font-size-base) var(--ifm-font-family-base);margin-bottom:.5rem;padding:.8rem;transition:border var(--ifm-transition-fast) ease;width:100%}.searchQueryInput_u2C7:focus,.searchVersionInput_m0Ui:focus{border-color:var(--docsearch-primary-color);outline:0}.searchQueryInput_u2C7::placeholder{color:var(--docsearch-muted-color)}.searchResultsColumn_JPFH{font-size:.9rem;font-weight:700}.algoliaLogo_rT1R{max-width:150px}.algoliaLogoPathFill_WdUC{fill:var(--ifm-font-color-base)}.searchResultItem_Tv2o{border-bottom:1px solid var(--ifm-toc-border-color);padding:1rem 0}.searchResultItemHeading_KbCB{font-weight:400;margin-bottom:0}.searchResultItemPath_lhe1{--ifm-breadcrumb-separator-size-multiplier:1;color:var(--ifm-color-content-secondary);font-size:.8rem}.searchResultItemSummary_AEaO{font-style:italic;margin:.5rem 0 0}.loadingSpinner_XVxU{animation:1s linear infinite a;border:.4em solid #eee;border-radius:50%;border-top:.4em solid var(--ifm-color-primary);height:3rem;margin:0 auto;width:3rem}@keyframes a{to{transform:rotate(1turn)}}.loader_vvXV{margin-top:2rem}.search-result-match{background:#ffd78e40;color:var(--docsearch-hit-color);padding:.09em 0}.backToTopButton_sjWU{background-color:var(--ifm-color-emphasis-200);border-radius:50%;bottom:1.3rem;box-shadow:var(--ifm-global-shadow-lw);height:3rem;opacity:0;position:fixed;right:1.3rem;transform:scale(0);transition:all var(--ifm-transition-fast) var(--ifm-transition-timing-default);visibility:hidden;width:3rem;z-index:calc(var(--ifm-z-index-fixed) - 1)}.backToTopButton_sjWU:after{background-color:var(--ifm-color-emphasis-1000);content:" ";display:inline-block;height:100%;-webkit-mask:var(--ifm-menu-link-sublist-icon) 50%/2rem 2rem no-repeat;mask:var(--ifm-menu-link-sublist-icon) 50%/2rem 2rem no-repeat;width:100%}.backToTopButtonShow_xfvO{opacity:1;transform:scale(1);visibility:visible}[data-theme=dark]:root{--docusaurus-collapse-button-bg:#ffffff0d;--docusaurus-collapse-button-bg-hover:#ffffff1a}.collapseSidebarButton_PEFL{display:none;margin:0}.docMainContainer_gTbr,.docPage__5DB{display:flex;width:100%}.docPage__5DB{flex:1 0}.docsWrapper_BCFX{display:flex;flex:1 0 auto}.authorCol_Hf19{flex-grow:1!important;max-width:inherit!important}.imageOnlyAuthorRow_pa_O{display:flex;flex-flow:row wrap}.imageOnlyAuthorCol_G86a{margin-left:.3rem;margin-right:.3rem}.sectionSkewed_JxZg{height:100%;left:0;overflow:hidden;position:relative;top:0;transform:skewY(-2deg);transform-origin:100% 0;width:100%}.sectionSkewedContainer_Xzhg{height:100%;position:absolute;width:100%}.leftLights_to8X:after{left:calc(50% - 1100px);top:-10%}.leftLights_to8X:after,.lightsTwo_Ax_R:after{background:radial-gradient(50% 50% at 50% 50%,#ffd60033 0,#ffa80000 100%);content:"";height:912px;mix-blend-mode:normal;pointer-events:none;position:absolute;width:1200px;will-change:filter}.lightsTwo_Ax_R:after{left:50%;top:0}.gradientBackground_goJV{background-image:linear-gradient(90deg,#d946ef,#fc0)}code[class*=language-],pre[class*=language-]{color:#393a34;direction:ltr;font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-size:.9em;-webkit-hyphens:none;hyphens:none;line-height:1.2em;tab-size:4;text-align:left;white-space:pre;word-break:normal;word-spacing:normal}pre>code[class*=language-]{font-size:1em}code[class*=language-] ::selection,code[class*=language-]::selection,pre[class*=language-] ::selection,pre[class*=language-]::selection{background:#b3d4fc}pre[class*=language-]{background-color:#f6f8fa;overflow:auto}:not(pre)>code[class*=language-]{background:#f8f8f8;border:1px solid #ddd;padding:1px .2em}.token.cdata,.token.comment,.token.doctype,.token.prolog{color:#998;font-style:italic}.token.attr-value,.token.string{color:#e3116c}.token.operator,.token.punctuation{color:#393a34}.language-autohotkey .token.keyword,.language-autohotkey .token.selector,.token.atrule,.token.attr-name,.token.keyword,.token.selector,.token.tag{color:#00009f}.language-autohotkey .token.tag,.token.deleted,.token.function{color:#9a050f}.token.bold,.token.function,.token.important{font-weight:700}div.twLandingPage{background-color:#f5f5f5}pre code{line-height:1.25rem}*,:after,:before{border:0 solid #e5e7eb}:after,:before{--tw-content:""}html{-webkit-font-smoothing:auto;-webkit-text-size-adjust:100%;font-feature-settings:normal;font-family:Inter;line-height:1.5;tab-size:4}body{line-height:inherit;margin:0}.twLandingPage hr{border-top-width:1px;color:inherit;height:0}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}.twLandingPage h1,.twLandingPage h2,.twLandingPage h3,.twLandingPage h4,.twLandingPage h5,.twLandingPage h6{font-size:inherit;font-weight:inherit}.twLandingPage a{color:inherit;text-decoration:inherit}.twLandingPage b,.twLandingPage strong{font-weight:bolder}.twLandingPage code,.twLandingPage kbd,.twLandingPage pre,.twLandingPage samp{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-size:1em}.twLandingPage small{font-size:80%}.twLandingPage sub,.twLandingPage sup{font-size:75%;line-height:0;position:relative;vertical-align:initial}.twLandingPage sub{bottom:-.25em}.twLandingPage sup{top:-.5em}.twLandingPage table{border-collapse:collapse;border-color:inherit;text-indent:0}.twLandingPage button,.twLandingPage input,.twLandingPage optgroup,.twLandingPage select,.twLandingPage textarea{color:inherit;font-family:inherit;font-size:100%;font-weight:inherit;line-height:inherit;margin:0;padding:0}.admonitionHeading_tbUL code,.twLandingPage button,.twLandingPage select{text-transform:none}.twLandingPage [type=button],.twLandingPage [type=reset],.twLandingPage [type=submit],.twLandingPage button{-webkit-appearance:button;background-color:initial;background-image:none}:-moz-focusring{outline:auto}:-moz-ui-invalid{box-shadow:none}progress{vertical-align:initial}::-webkit-inner-spin-button,::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}.twLandingPage summary{display:list-item}.twLandingPage fieldset{margin:0;padding:0}.twLandingPage menu,.twLandingPage ol,.twLandingPage ul{list-style:none;margin:0;padding:0}.twLandingPage textarea{resize:vertical}input::placeholder,textarea::placeholder{color:#9ca3af;opacity:1}[role=button],button{cursor:pointer}:disabled{cursor:default}.twLandingPage audio,.twLandingPage canvas,.twLandingPage embed,.twLandingPage iframe,.twLandingPage img,.twLandingPage object,.twLandingPage svg,.twLandingPage video{display:block;vertical-align:middle}.twLandingPage img,.twLandingPage video{height:auto;max-width:100%}.deployment-methods-grid,.social-auth-grid{grid-gap:.5rem;display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));margin-bottom:1rem}.auth-method-box,.deployment-method-box{border:1px solid var(--ifm-color-emphasis-300);border-radius:var(--ifm-pagination-nav-border-radius);display:flex;flex-direction:column;justify-content:center;padding:1.5rem;transition:.1s ease-in-out}.DocSearch-Button,.DocSearch-Button-Container{align-items:center;display:flex}.auth-method-box:hover,.deployment-method-box:hover{border-color:var(--ifm-pagination-nav-color-hover)}.auth-method-box h3,.deployment-method-box h3{color:var(--ifm-link-color);margin:0}.auth-method-box p,.auth-methods-info,.deployment-method-box p,.deployment-methods-info,.social-auth-info{color:var(--ifm-color-secondary-contrast-foreground)}.DocSearch-Button{background:var(--docsearch-searchbox-background);border:0;border-radius:40px;color:var(--docsearch-muted-color);cursor:pointer;font-weight:500;height:36px;justify-content:space-between;padding:0 8px;-webkit-user-select:none;user-select:none}.DocSearch-Button:active,.DocSearch-Button:focus,.DocSearch-Button:hover{background:var(--docsearch-searchbox-focus-background);box-shadow:var(--docsearch-searchbox-shadow);color:var(--docsearch-text-color);outline:0}.DocSearch-Search-Icon{stroke-width:1.6}.DocSearch-Hit-Tree,.DocSearch-Hit-action,.DocSearch-Hit-icon,.DocSearch-Reset{stroke-width:var(--docsearch-icon-stroke-width)}.DocSearch-Button .DocSearch-Search-Icon{color:var(--docsearch-text-color)}.DocSearch-Button-Placeholder{font-size:1rem;padding:0 12px 0 6px}.DocSearch-Input,.DocSearch-Link{-webkit-appearance:none;font:inherit}.DocSearch-Button-Keys{display:flex;min-width:calc(40px + .8em)}.DocSearch-Button-Key{align-items:center;background:var(--docsearch-key-gradient);border:0;border-radius:3px;box-shadow:var(--docsearch-key-shadow);color:var(--docsearch-muted-color);display:flex;height:18px;justify-content:center;margin-right:.4em;padding:0 0 2px;position:relative;top:-1px;width:20px}.DocSearch-Container{background-color:var(--docsearch-container-background);height:100vh;left:0;position:fixed;top:0;width:100vw;z-index:200}.DocSearch-Container a{text-decoration:none}.DocSearch-Link{appearance:none;background:none;border:0;color:var(--docsearch-highlight-color);cursor:pointer;margin:0;padding:0}.DocSearch-Modal{background:var(--docsearch-modal-background);border-radius:6px;box-shadow:var(--docsearch-modal-shadow);flex-direction:column;margin:60px auto auto;max-width:var(--docsearch-modal-width);position:relative}.DocSearch-SearchBar{display:flex;padding:var(--docsearch-spacing) var(--docsearch-spacing) 0}.DocSearch-Form{align-items:center;background:var(--docsearch-searchbox-focus-background);border-radius:4px;box-shadow:var(--docsearch-searchbox-shadow);display:flex;height:var(--docsearch-searchbox-height);margin:0;padding:0 var(--docsearch-spacing);position:relative;width:100%}.DocSearch-Input{appearance:none;background:#0000;border:0;color:var(--docsearch-text-color);flex:1;font-size:1.2em;height:100%;outline:0;padding:0 0 0 8px;width:80%}.DocSearch-Hit-action-button,.DocSearch-Reset{-webkit-appearance:none;border:0;cursor:pointer}.DocSearch-Input::placeholder{color:var(--docsearch-muted-color);opacity:1}.DocSearch-Input::-webkit-search-cancel-button,.DocSearch-Input::-webkit-search-decoration,.DocSearch-Input::-webkit-search-results-button,.DocSearch-Input::-webkit-search-results-decoration{display:none}.DocSearch-LoadingIndicator,.DocSearch-MagnifierLabel,.DocSearch-Reset{margin:0;padding:0}.DocSearch-Container--Stalled .DocSearch-LoadingIndicator,.DocSearch-MagnifierLabel,.DocSearch-Reset{align-items:center;color:var(--docsearch-highlight-color);display:flex;justify-content:center}.DocSearch-Cancel,.DocSearch-Container--Stalled .DocSearch-MagnifierLabel,.DocSearch-LoadingIndicator,.DocSearch-Reset[hidden]{display:none}.DocSearch-Reset{animation:.1s ease-in forwards b;appearance:none;background:none;border-radius:50%;color:var(--docsearch-icon-color);padding:2px;right:0}.DocSearch-Help,.DocSearch-HitsFooter,.DocSearch-Label{color:var(--docsearch-muted-color)}.DocSearch-Reset:hover{color:var(--docsearch-highlight-color)}.DocSearch-LoadingIndicator svg,.DocSearch-MagnifierLabel svg{height:24px;width:24px}.DocSearch-Dropdown{max-height:calc(var(--docsearch-modal-height) - var(--docsearch-searchbox-height) - var(--docsearch-spacing) - var(--docsearch-footer-height));min-height:var(--docsearch-spacing);overflow-y:auto;overflow-y:overlay;padding:0 var(--docsearch-spacing);scrollbar-color:var(--docsearch-muted-color) var(--docsearch-modal-background);scrollbar-width:thin}.DocSearch-Dropdown::-webkit-scrollbar{width:12px}.DocSearch-Dropdown::-webkit-scrollbar-track{background:#0000}.DocSearch-Dropdown::-webkit-scrollbar-thumb{background-color:var(--docsearch-muted-color);border:3px solid var(--docsearch-modal-background);border-radius:20px}.DocSearch-Dropdown ul{list-style:none;margin:0;padding:0}.DocSearch-Label{font-size:.75em;line-height:1.6em}.DocSearch-Help{font-size:.9em;margin:0;-webkit-user-select:none;user-select:none}.DocSearch-Title{font-size:1.2em}.DocSearch-Logo a{display:flex}.DocSearch-Logo svg{color:var(--docsearch-logo-color);margin-left:8px}.DocSearch-Hits:last-of-type{margin-bottom:24px}.DocSearch-Hits mark{background:none;color:var(--docsearch-highlight-color)}.DocSearch-HitsFooter{display:flex;font-size:.85em;justify-content:center;margin-bottom:var(--docsearch-spacing);padding:var(--docsearch-spacing)}.DocSearch-HitsFooter a{border-bottom:1px solid;color:inherit}.DocSearch-Hit{border-radius:4px;display:flex;padding-bottom:4px;position:relative}.DocSearch-Hit--deleting{opacity:0;transition:.25s linear}.DocSearch-Hit--favoriting{transform:scale(0);transform-origin:top center;transition:.25s linear .25s}.DocSearch-Hit a{background:var(--docsearch-hit-background);border-radius:4px;box-shadow:var(--docsearch-hit-shadow);display:block;padding-left:var(--docsearch-spacing);width:100%}.DocSearch-Hit-source{background:var(--docsearch-modal-background);color:var(--docsearch-highlight-color);font-size:.85em;font-weight:600;line-height:32px;margin:0 -4px;padding:8px 4px 0;position:sticky;top:0;z-index:10}.DocSearch-Hit-Tree{color:var(--docsearch-muted-color);height:var(--docsearch-hit-height);opacity:.5;width:24px}.DocSearch-Hit[aria-selected=true] a{background-color:var(--docsearch-highlight-color)}.DocSearch-Hit-Container{align-items:center;color:var(--docsearch-hit-color);display:flex;flex-direction:row;height:var(--docsearch-hit-height);padding:0 var(--docsearch-spacing) 0 0}.DocSearch-Hit-icon{height:20px;width:20px}.DocSearch-Hit-action,.DocSearch-Hit-icon{color:var(--docsearch-muted-color)}.DocSearch-Hit-action{align-items:center;display:flex;height:22px;width:22px}.DocSearch-Hit-action svg{display:block;height:18px;width:18px}.DocSearch-Hit-action+.DocSearch-Hit-action{margin-left:6px}.DocSearch-Hit-action-button{appearance:none;background:none;border-radius:50%;color:inherit;padding:2px}svg.DocSearch-Hit-Select-Icon{display:none}.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-Select-Icon,.tocCollapsibleContent_vkbj a{display:block}.DocSearch-Hit-action-button:focus,.DocSearch-Hit-action-button:hover{background:#0003;transition:background-color .1s ease-in}.DocSearch-Hit-action-button:focus path,.DocSearch-Hit-action-button:hover path{fill:#fff}.DocSearch-Hit-content-wrapper{display:flex;flex:1 1 auto;flex-direction:column;font-weight:500;justify-content:center;line-height:1.2em;margin:0 8px;overflow-x:hidden;position:relative;text-overflow:ellipsis;white-space:nowrap;width:80%}.DocSearch-Hit-title{font-size:.9em}.DocSearch-Hit-path{color:var(--docsearch-muted-color);font-size:.75em}.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-Tree,.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-action,.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-icon,.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-path,.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-text,.DocSearch-Hit[aria-selected=true] .DocSearch-Hit-title,.DocSearch-Hit[aria-selected=true] mark{color:var(--docsearch-hit-active-color)!important}.DocSearch-ErrorScreen,.DocSearch-NoResults,.DocSearch-StartScreen{font-size:.9em;margin:0 auto;padding:36px 0;text-align:center;width:80%}.DocSearch-Screen-Icon{color:var(--docsearch-muted-color);padding-bottom:12px}.DocSearch-NoResults-Prefill-List{display:inline-block;padding-bottom:24px;text-align:left}.DocSearch-NoResults-Prefill-List ul{display:inline-block;padding:8px 0 0}.DocSearch-NoResults-Prefill-List li{list-style-position:inside;list-style-type:"» "}.DocSearch-Prefill{-webkit-appearance:none;appearance:none;background:none;border:0;border-radius:1em;color:var(--docsearch-highlight-color);cursor:pointer;display:inline-block;font-size:1em;font-weight:700;padding:0}.DocSearch-Prefill:focus,.DocSearch-Prefill:hover{outline:0;text-decoration:underline}.DocSearch-Footer{align-items:center;background:var(--docsearch-footer-background);border-radius:0 0 8px 8px;box-shadow:var(--docsearch-footer-shadow);display:flex;flex-direction:row-reverse;flex-shrink:0;height:var(--docsearch-footer-height);justify-content:space-between;padding:0 var(--docsearch-spacing);position:relative;-webkit-user-select:none;user-select:none;width:100%;z-index:300}.DocSearch-Commands li,.DocSearch-Commands-Key{align-items:center;display:flex}.DocSearch-Commands{color:var(--docsearch-muted-color);display:flex;list-style:none;margin:0;padding:0}.DocSearch-Commands li:not(:last-of-type){margin-right:.8em}.DocSearch-Commands-Key{background:var(--docsearch-key-gradient);border:0;border-radius:2px;box-shadow:var(--docsearch-key-shadow);color:var(--docsearch-muted-color);height:18px;justify-content:center;margin-right:.4em;padding:0 0 1px;width:20px}.buttonGroup__atx button,.codeBlockContainer_Ckt0{background:var(--prism-background-color);color:var(--prism-color)}@keyframes b{0%{opacity:0}to{opacity:1}}.DocSearch-Button{margin:0;transition:all var(--ifm-transition-fast) var(--ifm-transition-timing-default)}.DocSearch-Container{z-index:calc(var(--ifm-z-index-fixed) + 1)}.auth-methods-grid{grid-gap:.5rem;display:grid;grid-template-columns:repeat(auto-fit,minmax(350px,1fr));margin-bottom:1rem}.codeBlockContainer_Ckt0{border-radius:var(--ifm-code-border-radius);box-shadow:var(--ifm-global-shadow-lw);margin-bottom:var(--ifm-leading)}.codeBlockContent_biex{border-radius:inherit;direction:ltr;position:relative}.codeBlockTitle_Ktv7{border-bottom:1px solid var(--ifm-color-emphasis-300);border-top-left-radius:inherit;border-top-right-radius:inherit;font-size:var(--ifm-code-font-size);font-weight:500;padding:.75rem var(--ifm-pre-padding)}.codeBlock_bY9V{--ifm-pre-background:var(--prism-background-color);margin:0;padding:0}.codeBlockTitle_Ktv7+.codeBlockContent_biex .codeBlock_bY9V{border-top-left-radius:0;border-top-right-radius:0}.codeBlockLines_e6Vv{float:left;font:inherit;min-width:100%;padding:var(--ifm-pre-padding)}.codeBlockLinesWithNumbering_o6Pm{display:table;padding:var(--ifm-pre-padding) 0}.buttonGroup__atx{column-gap:.2rem;display:flex;position:absolute;right:calc(var(--ifm-pre-padding)/2);top:calc(var(--ifm-pre-padding)/2)}.buttonGroup__atx button{align-items:center;border:1px solid var(--ifm-color-emphasis-300);border-radius:var(--ifm-global-radius);display:flex;line-height:0;opacity:0;padding:.4rem;transition:opacity var(--ifm-transition-fast) ease-in-out}.buttonGroup__atx button:focus-visible,.buttonGroup__atx button:hover{opacity:1!important}.theme-code-block:hover .buttonGroup__atx button{opacity:.4}:where(:root){--docusaurus-highlighted-code-line-bg:#484d5b}:where([data-theme=dark]){--docusaurus-highlighted-code-line-bg:#646464}.theme-code-block-highlighted-line{background-color:var(--docusaurus-highlighted-code-line-bg);display:block;margin:0 calc(var(--ifm-pre-padding)*-1);padding:0 var(--ifm-pre-padding)}.codeLine_lJS_{counter-increment:a;display:table-row}.codeLineNumber_Tfdd{background:var(--ifm-pre-background);display:table-cell;left:0;overflow-wrap:normal;padding:0 var(--ifm-pre-padding);position:sticky;text-align:right;width:1%}.codeLineNumber_Tfdd:before{content:counter(a);opacity:.4}.codeLineContent_feaV{padding-right:var(--ifm-pre-padding)}.iconEdit_Z9Sw{margin-right:.3em;vertical-align:sub}.tag_zVej{border:1px solid var(--docusaurus-tag-list-border);transition:border var(--ifm-transition-fast)}.tag_zVej:hover{--docusaurus-tag-list-border:var(--ifm-link-color);text-decoration:none}.tagRegular_sFm0{border-radius:var(--ifm-global-radius);font-size:90%;padding:.2rem .5rem .3rem}.tagWithCount_h2kH{align-items:center;border-left:0;display:flex;padding:0 .5rem 0 1rem;position:relative}.tagWithCount_h2kH:after,.tagWithCount_h2kH:before{border:1px solid var(--docusaurus-tag-list-border);content:"";position:absolute;top:50%;transition:inherit}.tagWithCount_h2kH:before{border-bottom:0;border-right:0;height:1.18rem;right:100%;transform:translate(50%,-50%) rotate(-45deg);width:1.18rem}.tagWithCount_h2kH:after{border-radius:50%;height:.5rem;left:0;transform:translateY(-50%);width:.5rem}.tagWithCount_h2kH span{background:var(--ifm-color-secondary);border-radius:var(--ifm-global-radius);color:var(--ifm-color-black);font-size:.7rem;line-height:1.2;margin-left:.3rem;padding:.1rem .4rem}.tag_Nnez{display:inline-block;margin:.5rem .5rem 0 1rem}.copyButtonIcons_eSgA{height:1.125rem;position:relative;width:1.125rem}.copyButtonIcon_y97N,.copyButtonSuccessIcon_LjdS{fill:currentColor;height:inherit;left:0;opacity:inherit;position:absolute;top:0;transition:all var(--ifm-transition-fast) ease;width:inherit}.copyButtonSuccessIcon_LjdS{color:#00d600;left:50%;opacity:0;top:50%;transform:translate(-50%,-50%) scale(.33)}.copyButtonCopied_obH4 .copyButtonIcon_y97N{opacity:0;transform:scale(.33)}.copyButtonCopied_obH4 .copyButtonSuccessIcon_LjdS{opacity:1;transform:translate(-50%,-50%) scale(1);transition-delay:75ms}.wordWrapButtonIcon_Bwma{height:1.2rem;width:1.2rem}.tags_jXut{display:inline}.tag_QGVx{display:inline-block;margin:0 .4rem .5rem 0}.lastUpdated_vwxv{font-size:smaller;font-style:italic;margin-top:.2rem}.tocCollapsibleButton_TO0P{align-items:center;display:flex;font-size:inherit;justify-content:space-between;padding:.4rem .8rem;width:100%}.tocCollapsibleButton_TO0P:after{background:var(--ifm-menu-link-sublist-icon) 50% 50%/2rem 2rem no-repeat;content:"";filter:var(--ifm-menu-link-sublist-icon-filter);height:1.25rem;transform:rotate(180deg);transition:transform var(--ifm-transition-fast);width:1.25rem}.tocCollapsibleButtonExpanded_MG3E:after,.tocCollapsibleExpanded_sAul{transform:none}.tocCollapsible_ETCw{background-color:var(--ifm-menu-color-background-active);border-radius:var(--ifm-global-radius);margin:1rem 0}.tocCollapsibleContent_vkbj>ul{border-left:none;border-top:1px solid var(--ifm-color-emphasis-300);font-size:15px;padding:.2rem 0}.tocCollapsibleContent_vkbj ul li{margin:.4rem .8rem}.details_lb9f{--docusaurus-details-summary-arrow-size:0.38rem;--docusaurus-details-transition:transform 200ms ease;--docusaurus-details-decoration-color:grey}.details_lb9f>summary{cursor:pointer;list-style:none;padding-left:1rem;position:relative}.details_lb9f>summary::-webkit-details-marker{display:none}.details_lb9f>summary:before{border-color:#0000 #0000 #0000 var(--docusaurus-details-decoration-color);border-style:solid;border-width:var(--docusaurus-details-summary-arrow-size);content:"";left:0;position:absolute;top:.45rem;transform:rotate(0);transform-origin:calc(var(--docusaurus-details-summary-arrow-size)/2) 50%;transition:var(--docusaurus-details-transition)}.collapsibleContent_i85q{border-top:1px solid var(--docusaurus-details-decoration-color);margin-top:1rem;padding-top:1rem}.details_b_Ee{--docusaurus-details-decoration-color:var(--ifm-alert-border-color);--docusaurus-details-transition:transform var(--ifm-transition-fast) ease;border:1px solid var(--ifm-alert-border-color);margin:0 0 var(--ifm-spacing-vertical)}.anchorWithStickyNavbar_LWe7{scroll-margin-top:calc(var(--ifm-navbar-height) + .5rem)}.anchorWithHideOnScrollNavbar_WYt5{scroll-margin-top:.5rem}.hash-link{opacity:0;padding-left:.5rem;transition:opacity var(--ifm-transition-fast);-webkit-user-select:none;user-select:none}.hash-link:before{content:"#"}.containsTaskList_mC6p{list-style:none}.img_ev3q{height:auto}.admonition_LlT9{margin-bottom:1em}.admonitionHeading_tbUL{font:var(--ifm-heading-font-weight) var(--ifm-h5-font-size)/var(--ifm-heading-line-height) var(--ifm-heading-font-family);margin-bottom:.3rem;text-transform:uppercase}.admonitionIcon_kALy{display:inline-block;margin-right:.4em;vertical-align:middle}.admonitionIcon_kALy svg{fill:var(--ifm-alert-foreground-color);display:inline-block;height:1.6em;width:1.6em}.blogPostFooterDetailsFull_mRVl{flex-direction:column}.tableOfContents_bqdL{max-height:calc(100vh - var(--ifm-navbar-height) - 2rem);overflow-y:auto;position:sticky;top:calc(var(--ifm-navbar-height) + 1rem)}.breadcrumbHomeIcon_YNFT{height:1.1rem;position:relative;top:1px;vertical-align:top;width:1.1rem}.breadcrumbsContainer_Z_bl{--ifm-breadcrumb-size-multiplier:0.8;margin-bottom:.8rem}@media (min-width:640px){.container,.lg\:container{max-width:640px}.sm\:ml-3{margin-left:.75rem!important}.sm\:ml-6{margin-left:1.5rem!important}.sm\:mt-0{margin-top:0!important}.sm\:mt-5{margin-top:1.25rem!important}.sm\:flex{display:flex!important}.sm\:w-full{width:100%!important}.sm\:max-w-md{max-width:28rem!important}.sm\:items-stretch{align-items:stretch!important}.sm\:space-x-4>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0!important;margin-left:calc(1rem*(1 - var(--tw-space-x-reverse)))!important;margin-right:calc(1rem*var(--tw-space-x-reverse))!important}.sm\:px-6{padding-left:1.5rem!important;padding-right:1.5rem!important}}@media (min-width:768px){.container,.lg\:container{max-width:768px}.md\:col-span-6{grid-column:span 6/span 6!important}.md\:-mx-6{margin-left:-1.5rem!important;margin-right:-1.5rem!important}.md\:-mt-12{margin-top:-3rem!important}.md\:-mt-6{margin-top:-1.5rem!important}.md\:mb-0{margin-bottom:0!important}.md\:mt-10{margin-top:2.5rem!important}.md\:mt-28{margin-top:7rem!important}.md\:block{display:block!important}.md\:h-10{height:2.5rem!important}.md\:w-\[180px\]{width:180px!important}.md\:max-w-none{max-width:none!important}.md\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))!important}.md\:grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))!important}.md\:gap-16{gap:4rem!important}.md\:gap-8{gap:2rem!important}.md\:p-12{padding:3rem!important}.md\:p-8{padding:2rem!important}.md\:px-20{padding-left:5rem!important;padding-right:5rem!important}.md\:py-24{padding-bottom:6rem!important;padding-top:6rem!important}.md\:py-36{padding-bottom:9rem!important;padding-top:9rem!important}.md\:pb-0{padding-bottom:0!important}.md\:pr-10{padding-right:2.5rem!important}}@media (min-width:997px){.collapseSidebarButton_PEFL,.expandButton_m80_{background-color:var(--docusaurus-collapse-button-bg)}:root{--docusaurus-announcement-bar-height:30px}.announcementBarClose_gvF7,.announcementBarPlaceholder_vyr4{flex-basis:50px}.searchBox_ZlJk{padding:var(--ifm-navbar-item-padding-vertical) var(--ifm-navbar-item-padding-horizontal)}.collapseSidebarButton_PEFL{border:1px solid var(--ifm-toc-border-color);border-radius:0;bottom:0;display:block!important;height:40px;position:sticky}.collapseSidebarButtonIcon_kv0_{margin-top:4px;transform:rotate(180deg)}.expandButtonIcon_BlDH,[dir=rtl] .collapseSidebarButtonIcon_kv0_{transform:rotate(0)}.collapseSidebarButton_PEFL:focus,.collapseSidebarButton_PEFL:hover,.expandButton_m80_:focus,.expandButton_m80_:hover{background-color:var(--docusaurus-collapse-button-bg-hover)}.menuHtmlItem_M9Kj{padding:var(--ifm-menu-link-padding-vertical) var(--ifm-menu-link-padding-horizontal)}.menu_SIkG{flex-grow:1;padding:.5rem}@supports (scrollbar-gutter:stable){.menu_SIkG{padding:.5rem 0 .5rem .5rem;scrollbar-gutter:stable}}.menuWithAnnouncementBar_GW3s{margin-bottom:var(--docusaurus-announcement-bar-height)}.sidebar_njMd{display:flex;flex-direction:column;height:100%;padding-top:var(--ifm-navbar-height);width:var(--doc-sidebar-width)}.sidebarWithHideableNavbar_wUlq{padding-top:0}.sidebarHidden_VK0M{opacity:0;visibility:hidden}.sidebarLogo_isFc{align-items:center;color:inherit!important;display:flex!important;margin:0 var(--ifm-navbar-padding-horizontal);max-height:var(--ifm-navbar-height);min-height:var(--ifm-navbar-height);text-decoration:none!important}.sidebarLogo_isFc img{height:2rem;margin-right:.5rem}.expandButton_m80_{align-items:center;display:flex;height:100%;justify-content:center;position:absolute;right:0;top:0;transition:background-color var(--ifm-transition-fast) ease;width:100%}[dir=rtl] .expandButtonIcon_BlDH{transform:rotate(180deg)}.docSidebarContainer_b6E3{border-right:1px solid var(--ifm-toc-border-color);-webkit-clip-path:inset(0);clip-path:inset(0);display:block;margin-top:calc(var(--ifm-navbar-height)*-1);transition:width var(--ifm-transition-fast) ease;width:var(--doc-sidebar-width);will-change:width}.docSidebarContainerHidden_b3ry{cursor:pointer;width:var(--doc-sidebar-hidden-width)}.sidebarViewport_Xe31{height:100%;max-height:100vh;position:sticky;top:0}.docMainContainer_gTbr{flex-grow:1;max-width:calc(100% - var(--doc-sidebar-width))}.docMainContainerEnhanced_Uz_u{max-width:calc(100% - var(--doc-sidebar-hidden-width))}.docItemWrapperEnhanced_czyv{max-width:calc(var(--ifm-container-width) + var(--doc-sidebar-width))!important}.lastUpdated_vwxv{text-align:right}.tocMobile_ITEo{display:none}.docItemCol_VOVn{max-width:75%!important}}@media (min-width:1024px){.container{max-width:1024px}@media (min-width:640px){.lg\:container{max-width:640px}}@media (min-width:768px){.lg\:container{max-width:768px}}@media (min-width:1024px){.lg\:container{max-width:1024px}}@media (min-width:1280px){.lg\:container{max-width:1280px}}@media (min-width:1536px){.lg\:container{max-width:1536px}}.lg\:container{width:100%;max-width:1024px}.lg\:top-\[1000px\]{top:1000px!important}.lg\:col-span-4{grid-column:span 4/span 4!important}.lg\:col-span-6{grid-column:span 6/span 6!important}.lg\:col-span-7{grid-column:span 7/span 7!important}.lg\:mt-0{margin-top:0!important}.lg\:mt-5{margin-top:1.25rem!important}.lg\:block{display:block!important}.lg\:inline{display:inline!important}.lg\:flex{display:flex!important}.lg\:grid{display:grid!important}.lg\:hidden{display:none!important}.lg\:w-2\/3{width:66.666667%!important}.lg\:max-w-none{max-width:none!important}.lg\:grid-cols-12{grid-template-columns:repeat(12,minmax(0,1fr))!important}.lg\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))!important}.lg\:grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))!important}.lg\:grid-cols-4{grid-template-columns:repeat(4,minmax(0,1fr))!important}.lg\:justify-between{justify-content:space-between!important}.lg\:gap-12{gap:3rem!important}.lg\:gap-16{gap:4rem!important}.lg\:gap-x-8{column-gap:2rem!important}.lg\:divide-x>:not([hidden])~:not([hidden]){--tw-divide-x-reverse:0!important;border-left-width:calc(1px*(1 - var(--tw-divide-x-reverse)))!important;border-right-width:calc(1px*var(--tw-divide-x-reverse))!important}.lg\:p-16{padding:4rem!important}.lg\:px-16{padding-left:4rem!important;padding-right:4rem!important}.lg\:px-24{padding-left:6rem!important;padding-right:6rem!important}.lg\:px-28{padding-left:7rem!important;padding-right:7rem!important}.lg\:py-24{padding-bottom:6rem!important;padding-top:6rem!important}.lg\:pb-8{padding-bottom:2rem!important}.lg\:pr-16{padding-right:4rem!important}.lg\:text-2xl{font-size:1.5rem!important;line-height:2rem!important}.lg\:text-5xl{font-size:3rem!important;line-height:1!important}.lg\:text-xl{font-size:1.25rem!important;line-height:1.75rem!important}.lg\:leading-tight{line-height:1.25!important}}@media (min-width:1280px){.container,.lg\:container{max-width:1280px}.xl\:col-span-1{grid-column:span 1/span 1!important}.xl\:col-span-2{grid-column:span 2/span 2!important}.xl\:col-span-4{grid-column:span 4/span 4!important}.xl\:col-span-7{grid-column:span 7/span 7!important}.xl\:col-start-6{grid-column-start:6!important}.xl\:ml-8{margin-left:2rem!important}.xl\:mt-0{margin-top:0!important}.xl\:flex{display:flex!important}.xl\:grid{display:grid!important}.xl\:w-0{width:0!important}.xl\:w-3\/5{width:60%!important}.xl\:flex-1{flex:1 1 0%!important}.xl\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))!important}.xl\:grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))!important}.xl\:items-center{align-items:center!important}.xl\:gap-x-16{column-gap:4rem!important}.xl\:gap-x-24{column-gap:6rem!important}.xl\:px-20{padding-left:5rem!important;padding-right:5rem!important}}@media (min-width:1440px){.container{max-width:var(--ifm-container-width-xl)}}@media (min-width:1536px){.container,.lg\:container{max-width:1536px}}@media (max-width:996px){.col{--ifm-col-width:100%;flex-basis:var(--ifm-col-width);margin-left:0}.footer{--ifm-footer-padding-horizontal:0}.colorModeToggle_DEke,.footer__link-separator,.navbar__item,.sidebar_re4s,.tableOfContents_bqdL{display:none}.footer__col{margin-bottom:calc(var(--ifm-spacing-vertical)*3)}.footer__link-item{display:block}.hero{padding-left:0;padding-right:0}.navbar>.container,.navbar>.container-fluid{padding:0}.navbar__toggle{display:inherit}.navbar__search-input{width:9rem}.pills--block,.tabs--block{flex-direction:column}.searchBox_ZlJk{position:absolute;right:var(--ifm-navbar-padding-horizontal)}.docItemContainer_F8PC{padding:0 .3rem}}@media only screen and (max-width:996px){.searchQueryColumn_RTkw,.searchResultsColumn_JPFH{max-width:60%!important}.searchLogoColumn_rJIA,.searchVersionColumn_ypXd{max-width:40%!important}.searchLogoColumn_rJIA{padding-left:0!important}}@media (max-width:768px){.DocSearch-Button-Keys,.DocSearch-Button-Placeholder,.DocSearch-Commands,.DocSearch-Hit-Tree{display:none}:root{--docsearch-spacing:10px;--docsearch-footer-height:40px}.DocSearch-Dropdown{height:100%;max-height:calc(var(--docsearch-vh,1vh)*100 - var(--docsearch-searchbox-height) - var(--docsearch-spacing) - var(--docsearch-footer-height))}.DocSearch-Container{height:100vh;height:-webkit-fill-available;height:calc(var(--docsearch-vh,1vh)*100);position:absolute}.DocSearch-Footer{border-radius:0;bottom:0;position:absolute}.DocSearch-Hit-content-wrapper{display:flex;position:relative;width:80%}.DocSearch-Modal{border-radius:0;box-shadow:none;height:100vh;height:-webkit-fill-available;height:calc(var(--docsearch-vh,1vh)*100);margin:0;max-width:100%;width:100%}.DocSearch-Cancel{-webkit-appearance:none;appearance:none;background:none;border:0;color:var(--docsearch-highlight-color);cursor:pointer;display:inline-block;flex:none;font:inherit;font-size:1em;font-weight:500;margin-left:var(--docsearch-spacing);outline:0;overflow:hidden;padding:0;-webkit-user-select:none;user-select:none;white-space:nowrap}}@media (max-width:576px){.markdown h1:first-child{--ifm-h1-font-size:2rem}.markdown>h2{--ifm-h2-font-size:1.5rem}.markdown>h3{--ifm-h3-font-size:1.25rem}.title_f1Hy{font-size:2rem}}@media screen and (max-width:576px){.searchQueryColumn_RTkw{max-width:100%!important}.searchVersionColumn_ypXd{max-width:100%!important;padding-left:var(--ifm-spacing-horizontal)!important}}@media (hover:hover){.backToTopButton_sjWU:hover{background-color:var(--ifm-color-emphasis-300)}}@media (pointer:fine){.thin-scrollbar{scrollbar-width:thin}.thin-scrollbar::-webkit-scrollbar{height:var(--ifm-scrollbar-size);width:var(--ifm-scrollbar-size)}.thin-scrollbar::-webkit-scrollbar-track{background:var(--ifm-scrollbar-track-background-color);border-radius:10px}.thin-scrollbar::-webkit-scrollbar-thumb{background:var(--ifm-scrollbar-thumb-background-color);border-radius:10px}.thin-scrollbar::-webkit-scrollbar-thumb:hover{background:var(--ifm-scrollbar-thumb-hover-background-color)}}@media (prefers-reduced-motion:reduce){:root{--ifm-transition-fast:0ms;--ifm-transition-slow:0ms}}@media screen and (prefers-reduced-motion:reduce){.DocSearch-Reset{stroke-width:var(--docsearch-icon-stroke-width);animation:none;-webkit-appearance:none;appearance:none;background:none;border:0;border-radius:50%;color:var(--docsearch-icon-color);cursor:pointer;right:0}.DocSearch-Hit--deleting,.DocSearch-Hit--favoriting{transition:none}.DocSearch-Hit-action-button:focus,.DocSearch-Hit-action-button:hover{background:#0003;transition:none}}@media print{.announcementBar_mb4j,.footer,.menu,.navbar,.pagination-nav,.table-of-contents,.tocMobile_ITEo{display:none}.tabs{page-break-inside:avoid}.codeBlockLines_e6Vv{white-space:pre-wrap}} \ No newline at end of file diff --git a/assets/js/0245f0fe.33d08b2d.js b/assets/js/0245f0fe.33d08b2d.js new file mode 100644 index 0000000000..7692f59098 --- /dev/null +++ b/assets/js/0245f0fe.33d08b2d.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[90665],{3905:(e,t,n)=>{n.d(t,{Zo:()=>m,kt:()=>g});var a=n(67294);function r(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 s(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=a.createContext({}),p=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},m=function(e){var t=p(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)}},c=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,l=e.parentName,m=o(e,["components","mdxType","originalType","parentName"]),u=p(n),c=r,g=u["".concat(l,".").concat(c)]||u[c]||d[c]||i;return n?a.createElement(g,s(s({ref:t},m),{},{components:n})):a.createElement(g,s({ref:t},m))}));function g(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,s=new Array(i);s[0]=c;var o={};for(var l in t)hasOwnProperty.call(t,l)&&(o[l]=t[l]);o.originalType=e,o[u]="string"==typeof e?e:r,s[1]=o;for(var p=2;p{n.d(t,{Z:()=>s});var a=n(67294),r=n(86010);const i={tabItem:"tabItem_Ymn6"};function s(e){let{children:t,hidden:n,className:s}=e;return a.createElement("div",{role:"tabpanel",className:(0,r.Z)(i.tabItem,s),hidden:n},t)}},74866:(e,t,n)=>{n.d(t,{Z:()=>v});var a=n(87462),r=n(67294),i=n(86010),s=n(12466),o=n(16550),l=n(91980),p=n(67392),m=n(50012);function u(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??u(n);return function(e){const t=(0,p.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 c(e){let{value:t,tabValues:n}=e;return n.some((e=>e.value===t))}function g(e){let{queryString:t=!1,groupId:n}=e;const a=(0,o.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 h(e){const{defaultValue:t,queryString:n=!1,groupId:a}=e,i=d(e),[s,o]=(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(!c({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,p]=g({queryString:n,groupId:a}),[u,h]=function(e){let{groupId:t}=e;const n=function(e){return e?`docusaurus.tab.${e}`:null}(t),[a,i]=(0,m.Nk)(n);return[a,(0,r.useCallback)((e=>{n&&i.set(e)}),[n,i])]}({groupId:a}),k=(()=>{const e=l??u;return c({value:e,tabValues:i})?e:null})();(0,r.useLayoutEffect)((()=>{k&&o(k)}),[k]);return{selectedValue:s,selectValue:(0,r.useCallback)((e=>{if(!c({value:e,tabValues:i}))throw new Error(`Can't select invalid tab value=${e}`);o(e),p(e),h(e)}),[p,h,i]),tabValues:i}}var k=n(72389);const f={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};function y(e){let{className:t,block:n,selectedValue:o,selectValue:l,tabValues:p}=e;const m=[],{blockElementScrollPositionUntilNextRender:u}=(0,s.o5)(),d=e=>{const t=e.currentTarget,n=m.indexOf(t),a=p[n].value;a!==o&&(u(t),l(a))},c=e=>{let t=null;switch(e.key){case"Enter":d(e);break;case"ArrowRight":{const n=m.indexOf(e.currentTarget)+1;t=m[n]??m[0];break}case"ArrowLeft":{const n=m.indexOf(e.currentTarget)-1;t=m[n]??m[m.length-1];break}}t?.focus()};return r.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,i.Z)("tabs",{"tabs--block":n},t)},p.map((e=>{let{value:t,label:n,attributes:s}=e;return r.createElement("li",(0,a.Z)({role:"tab",tabIndex:o===t?0:-1,"aria-selected":o===t,key:t,ref:e=>m.push(e),onKeyDown:c,onClick:d},s,{className:(0,i.Z)("tabs__item",f.tabItem,s?.className,{"tabs__item--active":o===t})}),n??t)})))}function N(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 b(e){const t=h(e);return r.createElement("div",{className:(0,i.Z)("tabs-container",f.tabList)},r.createElement(y,(0,a.Z)({},e,t)),r.createElement(N,(0,a.Z)({},e,t)))}function v(e){const t=(0,k.Z)();return r.createElement(b,(0,a.Z)({key:String(t)},e))}},85798:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>m,contentTitle:()=>l,default:()=>g,frontMatter:()=>o,metadata:()=>p,toc:()=>u});var a=n(87462),r=(n(67294),n(3905)),i=n(85162),s=n(74866);const o={title:"Migration from 0.13.X to 0.14.X"},l=void 0,p={unversionedId:"migration-guides/migrate-from-0-13-to-0-14",id:"version-0.15.0/migration-guides/migrate-from-0-13-to-0-14",title:"Migration from 0.13.X to 0.14.X",description:"This guide only covers the migration from 0.13.X to 0.14.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.",source:"@site/versioned_docs/version-0.15.0/migration-guides/migrate-from-0-13-to-0-14.md",sourceDirName:"migration-guides",slug:"/migration-guides/migrate-from-0-13-to-0-14",permalink:"/docs/migration-guides/migrate-from-0-13-to-0-14",draft:!1,editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/versioned_docs/version-0.15.0/migration-guides/migrate-from-0-13-to-0-14.md",tags:[],version:"0.15.0",frontMatter:{title:"Migration from 0.13.X to 0.14.X"},sidebar:"docs",previous:{title:"Migration from 0.14.X to 0.15.X",permalink:"/docs/migration-guides/migrate-from-0-14-to-0-15"},next:{title:"Migration from 0.12.X to 0.13.X",permalink:"/docs/migration-guides/migrate-from-0-12-to-0-13"}},m={},u=[{value:"What's new in 0.14.0?",id:"whats-new-in-0140",level:2},{value:"Using Prisma Schema file directly",id:"using-prisma-schema-file-directly",level:3},{value:"Better auth user API",id:"better-auth-user-api",level:3},{value:"How to migrate?",id:"how-to-migrate",level:2},{value:"Bump the version and update tsconfig.json",id:"bump-the-version-and-update-tsconfigjson",level:3},{value:"Migrate to the new schema.prisma file",id:"migrate-to-the-new-schemaprisma-file",level:3},{value:"Migrate how you access user auth fields",id:"migrate-how-you-access-user-auth-fields",level:3},{value:"Migrate the database",id:"migrate-the-database",level:3}],d={toc:u},c="wrapper";function g(e){let{components:t,...n}=e;return(0,r.kt)(c,(0,a.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("admonition",{title:"Are you on 0.11.X or earlier?",type:"note"},(0,r.kt)("p",{parentName:"admonition"},"This guide only covers the migration from ",(0,r.kt)("strong",{parentName:"p"},"0.13.X to 0.14.X"),". If you are migrating from 0.11.X or earlier, please read the ",(0,r.kt)("a",{parentName:"p",href:"/docs/migration-guides/migrate-from-0-11-to-0-12"},"migration guide from 0.11.X to 0.12.X")," first.")),(0,r.kt)("h2",{id:"whats-new-in-0140"},"What's new in 0.14.0?"),(0,r.kt)("h3",{id:"using-prisma-schema-file-directly"},"Using Prisma Schema file directly"),(0,r.kt)("p",null,"Before 0.14.0, users defined their entities in the ",(0,r.kt)("inlineCode",{parentName:"p"},".wasp")," file, and Wasp generated the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file based on that. This approach had some limitations, and users couldn't use some advanced Prisma features."),(0,r.kt)("p",null,"Wasp now exposes the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file directly to the user. You now define your entities in the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file and Wasp uses that to generate the database schema and Prisma client. You can use all the Prisma features directly in the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file. Simply put, the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file is now the source of truth for your database schema."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.13.0"\n },\n title: "MyApp",\n db: {\n system: PostgreSQL\n },\n}\n\nentity User {=psl\n id Int @id @default(autoincrement())\n tasks Task[]\npsl=}\n\nentity Task {=psl\n id Int @id @default(autoincrement())\n description String\n isDone Boolean\n userId Int\n user User @relation(fields: [userId], references: [id])\npsl=}\n'))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.14.0"\n },\n title: "MyApp",\n}\n')),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "postgresql"\n url = env("DATABASE_URL")\n}\n\ngenerator client {\n provider = "prisma-client-js"\n}\n\nmodel User {\n id Int @id @default(autoincrement())\n tasks Task[]\n}\n\nmodel Task {\n id Int @id @default(autoincrement())\n description String\n isDone Boolean\n userId Int\n user User @relation(fields: [userId], references: [id])\n}\n')))),(0,r.kt)("h3",{id:"better-auth-user-api"},"Better auth user API"),(0,r.kt)("p",null,"Wasp introduced a much simpler API for accessing user auth fields like ",(0,r.kt)("inlineCode",{parentName:"p"},"username"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"email")," or ",(0,r.kt)("inlineCode",{parentName:"p"},"isEmailVerified")," on the ",(0,r.kt)("inlineCode",{parentName:"p"},"user")," object. You don't need to use helper functions every time you want to access the user's ",(0,r.kt)("inlineCode",{parentName:"p"},"username")," or do extra steps to get proper typing."),(0,r.kt)("h2",{id:"how-to-migrate"},"How to migrate?"),(0,r.kt)("p",null,"To migrate your app to Wasp 0.14.x, you must:"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},"Bump the version in ",(0,r.kt)("inlineCode",{parentName:"li"},"main.wasp")," and update your ",(0,r.kt)("inlineCode",{parentName:"li"},"tsconfig.json"),"."),(0,r.kt)("li",{parentName:"ol"},"Migrate your entities into the new ",(0,r.kt)("inlineCode",{parentName:"li"},"schema.prisma")," file."),(0,r.kt)("li",{parentName:"ol"},"Update code that accesses user fields.")),(0,r.kt)("h3",{id:"bump-the-version-and-update-tsconfigjson"},"Bump the version and update ",(0,r.kt)("inlineCode",{parentName:"h3"},"tsconfig.json")),(0,r.kt)("p",null,"Let's start with something simple. Update the version field in your Wasp file to ",(0,r.kt)("inlineCode",{parentName:"p"},"^0.14.0"),":"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app MyApp {\n wasp: {\n // highlight-next-line\n version: "^0.14.0"\n },\n}\n')),(0,r.kt)("p",null,"To ensure your project works correctly with Wasp 0.14.0, you must also update your\n",(0,r.kt)("inlineCode",{parentName:"p"},"tsconfig.json")," file."),(0,r.kt)("p",null,"If you haven't changed anything in your project's ",(0,r.kt)("inlineCode",{parentName:"p"},"tsconfig.json")," file (this is\nthe case for most users), just replace its contents with the new version shown\nbelow."),(0,r.kt)("p",null,"If you have made changes to your ",(0,r.kt)("inlineCode",{parentName:"p"},"tsconfig.json")," file, we recommend taking the\nnew version of the file and reapplying them."),(0,r.kt)("p",null,"Here's the new version of the ",(0,r.kt)("inlineCode",{parentName:"p"},"tsconfig.json")," file:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-json",metastring:"title=tsconfig.json",title:"tsconfig.json"},'// =============================== IMPORTANT =================================\n//\n// This file is only used for Wasp IDE support. You can change it to configure\n// your IDE checks, but none of these options will affect the TypeScript\n// compiler. Proper TS compiler configuration in Wasp is coming soon :)\n{\n "compilerOptions": {\n "module": "esnext",\n "target": "esnext",\n // We\'re bundling all code in the end so this is the most appropriate option,\n // it\'s also important for autocomplete to work properly.\n "moduleResolution": "bundler",\n // JSX support\n "jsx": "preserve",\n "strict": true,\n // Allow default imports.\n "esModuleInterop": true,\n "lib": ["dom", "dom.iterable", "esnext"],\n "allowJs": true,\n "typeRoots": [\n // This is needed to properly support Vitest testing with jest-dom matchers.\n // Types for jest-dom are not recognized automatically and Typescript complains\n // about missing types e.g. when using `toBeInTheDocument` and other matchers.\n "node_modules/@testing-library",\n // Specifying type roots overrides the default behavior of looking at the\n // node_modules/@types folder so we had to list it explicitly.\n // Source 1: https://www.typescriptlang.org/tsconfig#typeRoots\n // Source 2: https://github.com/testing-library/jest-dom/issues/546#issuecomment-1889884843\n "node_modules/@types"\n ],\n // Since this TS config is used only for IDE support and not for\n // compilation, the following directory doesn\'t exist. We need to specify\n // it to prevent this error:\n // https://stackoverflow.com/questions/42609768/typescript-error-cannot-write-file-because-it-would-overwrite-input-file\n "outDir": ".wasp/phantom"\n }\n}\n')),(0,r.kt)("h3",{id:"migrate-to-the-new-schemaprisma-file"},"Migrate to the new ",(0,r.kt)("inlineCode",{parentName:"h3"},"schema.prisma")," file"),(0,r.kt)("p",null,"To use the new ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file, you need to move your entities from the ",(0,r.kt)("inlineCode",{parentName:"p"},".wasp")," file to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file."),(0,r.kt)("p",null,"1","."," ",(0,r.kt)("strong",{parentName:"p"},"Create a new ",(0,r.kt)("inlineCode",{parentName:"strong"},"schema.prisma")," file")),(0,r.kt)("p",null,"Create a new file named ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," in the root of your project:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-c"},".\n\u251c\u2500\u2500 main.wasp\n...\n// highlight-next-line\n\u251c\u2500\u2500 schema.prisma\n\u251c\u2500\u2500 src\n\u251c\u2500\u2500 tsconfig.json\n\u2514\u2500\u2500 vite.config.ts\n")),(0,r.kt)("p",null,"2","."," ",(0,r.kt)("strong",{parentName:"p"},"Add the ",(0,r.kt)("inlineCode",{parentName:"strong"},"datasource")," block")," to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file"),(0,r.kt)("p",null,"This block specifies the database type and connection URL:"),(0,r.kt)(s.Z,{groupId:"db",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"sqlite",label:"Sqlite",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "sqlite"\n url = env("DATABASE_URL")\n}\n'))),(0,r.kt)(i.Z,{value:"postgresql",label:"PostgreSQL",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "postgresql"\n url = env("DATABASE_URL")\n}\n')))),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"The ",(0,r.kt)("inlineCode",{parentName:"p"},"provider")," should be either ",(0,r.kt)("inlineCode",{parentName:"p"},'"postgresql"')," or ",(0,r.kt)("inlineCode",{parentName:"p"},'"sqlite"'),".")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"The ",(0,r.kt)("inlineCode",{parentName:"p"},"url")," must be set to ",(0,r.kt)("inlineCode",{parentName:"p"},'env("DATABASE_URL")')," so that Wasp can inject the database URL from the environment variables."))),(0,r.kt)("p",null,"3","."," ",(0,r.kt)("strong",{parentName:"p"},"Add the ",(0,r.kt)("inlineCode",{parentName:"strong"},"generator")," block")," to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file"),(0,r.kt)("p",null,"This block specifies the Prisma Client generator Wasp uses:"),(0,r.kt)(s.Z,{groupId:"db",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"sqlite",label:"Sqlite",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "sqlite"\n url = env("DATABASE_URL")\n}\n\n// highlight-start\ngenerator client {\n provider = "prisma-client-js"\n}\n// highlight-end\n'))),(0,r.kt)(i.Z,{value:"postgresql",label:"PostgreSQL",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "postgresql"\n url = env("DATABASE_URL")\n}\n\n// highlight-start\ngenerator client {\n provider = "prisma-client-js"\n}\n// highlight-end\n')))),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"The ",(0,r.kt)("inlineCode",{parentName:"li"},"provider")," should be set to ",(0,r.kt)("inlineCode",{parentName:"li"},'"prisma-client-js"'),".")),(0,r.kt)("p",null,"4","."," ",(0,r.kt)("strong",{parentName:"p"},"Move your entities")," to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file"),(0,r.kt)("p",null,"Move the entities from the ",(0,r.kt)("inlineCode",{parentName:"p"},".wasp")," file to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file:"),(0,r.kt)(s.Z,{groupId:"db",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"sqlite",label:"Sqlite",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "sqlite"\n url = env("DATABASE_URL")\n}\n\ngenerator client {\n provider = "prisma-client-js"\n}\n\n// There are some example entities, you should move your entities here\n// highlight-start\nmodel User {\n id Int @id @default(autoincrement())\n tasks Task[]\n}\n\nmodel Task {\n id Int @id @default(autoincrement())\n description String\n isDone Boolean\n userId Int\n user User @relation(fields: [userId], references: [id])\n}\n// highlight-end\n'))),(0,r.kt)(i.Z,{value:"postgresql",label:"PostgreSQL",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "postgresql"\n url = env("DATABASE_URL")\n}\n\ngenerator client {\n provider = "prisma-client-js"\n}\n\n// There are some example entities, you should move your entities here\n// highlight-start\nmodel User {\n id Int @id @default(autoincrement())\n tasks Task[]\n}\n\nmodel Task {\n id Int @id @default(autoincrement())\n description String\n isDone Boolean\n userId Int\n user User @relation(fields: [userId], references: [id])\n}\n// highlight-end\n')))),(0,r.kt)("p",null,"When moving the entities over, you'll need to change ",(0,r.kt)("inlineCode",{parentName:"p"},"entity")," to ",(0,r.kt)("inlineCode",{parentName:"p"},"model")," and remove the ",(0,r.kt)("inlineCode",{parentName:"p"},"=psl")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"psl=")," tags."),(0,r.kt)("p",null,"If you had the following in the ",(0,r.kt)("inlineCode",{parentName:"p"},".wasp")," file:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},"entity Task {=psl\n // Stays the same\npsl=}\n")),(0,r.kt)("p",null,"... it would look like this in the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},"model Task {\n // Stays the same\n}\n")),(0,r.kt)("p",null,"5","."," ",(0,r.kt)("strong",{parentName:"p"},"Remove ",(0,r.kt)("inlineCode",{parentName:"strong"},"app.db.system"))," field from the Wasp file"),(0,r.kt)("p",null,"We now configure the DB system in the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file, so there is no need for that field in the Wasp file."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},"app MyApp {\n // ...\n db: {\n // highlight-next-line\n system: PostgreSQL,\n }\n}\n")),(0,r.kt)("p",null,"6","."," ",(0,r.kt)("strong",{parentName:"p"},"Migrate Prisma preview features config")," to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file"),(0,r.kt)("p",null,"If you didn't use any Prisma preview features, you can skip this step."),(0,r.kt)("p",null,"If you had the following in the ",(0,r.kt)("inlineCode",{parentName:"p"},".wasp")," file:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app MyApp {\n // ...\n db: {\n // highlight-start\n prisma: {\n clientPreviewFeatures: ["postgresqlExtensions"]\n dbExtensions: [\n { name: "hstore", schema: "myHstoreSchema" },\n { name: "pg_trgm" },\n { name: "postgis", version: "2.1" },\n ]\n }\n // highlight-end\n }\n}\n')),(0,r.kt)("p",null,"... it will become this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "postgresql"\n url = env("DATABASE_URL")\n // highlight-next-line\n extensions = [hstore(schema: "myHstoreSchema"), pg_trgm, postgis(version: "2.1")]\n}\n\ngenerator client {\n provider = "prisma-client-js"\n // highlight-next-line\n previewFeatures = ["postgresqlExtensions"]\n}\n')),(0,r.kt)("p",null,"All that's left to do is migrate the database."),(0,r.kt)("p",null,"To avoid type errors, it's best to take care of database migrations after you've migrated the rest of the code.\nSo, just keep reading, and we will remind you to migrate the database as ",(0,r.kt)("a",{parentName:"p",href:"#migrate-the-database"},"the last step of the migration guide"),"."),(0,r.kt)("p",null,"Read more about the ",(0,r.kt)("a",{parentName:"p",href:"/docs/data-model/prisma-file"},"Prisma Schema File")," and how Wasp uses it to generate the database schema and Prisma client."),(0,r.kt)("h3",{id:"migrate-how-you-access-user-auth-fields"},"Migrate how you access user auth fields"),(0,r.kt)("p",null,"We had to make a couple of breaking changes to reach the new simpler API."),(0,r.kt)("p",null,"Follow the steps below to migrate:"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Replace the ",(0,r.kt)("inlineCode",{parentName:"strong"},"getUsername")," helper")," with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities.username.id")),(0,r.kt)("p",{parentName:"li"},"If you didn't use the ",(0,r.kt)("inlineCode",{parentName:"p"},"getUsername")," helper in your code, you can skip this step."),(0,r.kt)("p",{parentName:"li"},"This helper changed and it no longer works with the ",(0,r.kt)("inlineCode",{parentName:"p"},"user")," you receive as a prop on a page or through the ",(0,r.kt)("inlineCode",{parentName:"p"},"context"),". You'll need to replace it with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities.username.id"),"."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { getUsername, AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const username = getUsername(user)\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"import { getUsername } from 'wasp/auth'\n\nexport const createTask: CreateTask<...> = async (args, context) => {\n const username = getUsername(context.user)\n // ...\n}\n"))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const username = user.identities.username?.id\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"export const createTask: CreateTask<...> = async (args, context) => {\n const username = context.user.identities.username?.id\n // ...\n}\n"))))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Replace the ",(0,r.kt)("inlineCode",{parentName:"strong"},"getEmail")," helper")," with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities.email.id")),(0,r.kt)("p",{parentName:"li"},"If you didn't use the ",(0,r.kt)("inlineCode",{parentName:"p"},"getEmail")," helper in your code, you can skip this step."),(0,r.kt)("p",{parentName:"li"},"This helper changed and it no longer works with the ",(0,r.kt)("inlineCode",{parentName:"p"},"user")," you receive as a prop on a page or through the ",(0,r.kt)("inlineCode",{parentName:"p"},"context"),". You'll need to replace it with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities.email.id"),"."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { getEmail, AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const email = getEmail(user)\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"import { getEmail } from 'wasp/auth'\n\nexport const createTask: CreateTask<...> = async (args, context) => {\n const email = getEmail(context.user)\n // ...\n}\n"))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const email = user.identities.email?.id\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"export const createTask: CreateTask<...> = async (args, context) => {\n const email = context.user.identities.email?.id\n // ...\n}\n"))))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Replace accessing ",(0,r.kt)("inlineCode",{parentName:"strong"},"providerData"))," with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities..")),(0,r.kt)("p",{parentName:"li"},"If you didn't use any data from the ",(0,r.kt)("inlineCode",{parentName:"p"},"providerData")," object, you can skip this step."),(0,r.kt)("p",{parentName:"li"},"Replace ",(0,r.kt)("inlineCode",{parentName:"p"},"")," with the provider name (for example ",(0,r.kt)("inlineCode",{parentName:"p"},"username"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"email"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"google"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"github"),", etc.) and ",(0,r.kt)("inlineCode",{parentName:"p"},"")," with the field you want to access (for example ",(0,r.kt)("inlineCode",{parentName:"p"},"isEmailVerified"),")."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { findUserIdentity, AuthUser } from 'wasp/auth'\n\nfunction getProviderData(user: AuthUser) {\n const emailIdentity = findUserIdentity(user, 'email')\n // We needed this before check for proper type support\n return emailIdentity && 'isEmailVerified' in emailIdentity.providerData\n ? emailIdentity.providerData\n : null\n}\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const providerData = getProviderData(user)\n const isEmailVerified = providerData ? providerData.isEmailVerified : null\n // ...\n}\n"))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n // The email object is properly typed, so we can access `isEmailVerified` directly\n const isEmailVerified = user.identities.email?.isEmailVerified\n // ...\n}\n"))))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Use ",(0,r.kt)("inlineCode",{parentName:"strong"},"getFirstProviderUserId")," directly")," on the user object"),(0,r.kt)("p",{parentName:"li"},"If you didn't use ",(0,r.kt)("inlineCode",{parentName:"p"},"getFirstProviderUserId")," in your code, you can skip this step."),(0,r.kt)("p",{parentName:"li"},"You should replace ",(0,r.kt)("inlineCode",{parentName:"p"},"getFirstProviderUserId(user)")," with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.getFirstProviderUserId()"),"."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { getFirstProviderUserId, AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const userId = getFirstProviderUserId(user)\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"import { getFirstProviderUserId } from 'wasp/auth'\n\nexport const createTask: CreateTask<...> = async (args, context) => {\n const userId = getFirstProviderUserId(context.user)\n // ...\n}\n"))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const userId = user.getFirstProviderUserId()\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"export const createTask: CreateTask<...> = async (args, context) => {\n const userId = user.getFirstProviderUserId()\n // ...\n}\n"))))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Replace ",(0,r.kt)("inlineCode",{parentName:"strong"},"findUserIdentity"))," with checks on ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities.")),(0,r.kt)("p",{parentName:"li"},"If you didn't use ",(0,r.kt)("inlineCode",{parentName:"p"},"findUserIdentity")," in your code, you can skip this step."),(0,r.kt)("p",{parentName:"li"},"Instead of using ",(0,r.kt)("inlineCode",{parentName:"p"},"findUserIdentity")," to get the identity object, you can directly check if the identity exists on the ",(0,r.kt)("inlineCode",{parentName:"p"},"identities")," object."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { findUserIdentity, AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const usernameIdentity = findUserIdentity(user, 'username')\n if (usernameIdentity) {\n // ...\n }\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"import { findUserIdentity } from 'wasp/auth'\n\nexport const createTask: CreateTask<...> = async (args, context) => {\n const usernameIdentity = findUserIdentity(context.user, 'username')\n if (usernameIdentity) {\n // ...\n }\n}\n"))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n if (user.identities.username) {\n // ...\n }\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"export const createTask: CreateTask<...> = async (args, context) => {\n if (context.user.identities.username) {\n // ...\n }\n}\n")))))),(0,r.kt)("h3",{id:"migrate-the-database"},"Migrate the database"),(0,r.kt)("p",null,"Finally, you can ",(0,r.kt)("strong",{parentName:"p"},"Run the Wasp CLI")," to regenerate the new Prisma client:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"wasp db migrate-dev\n")),(0,r.kt)("p",null,"This command generates the Prisma client based on the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file."),(0,r.kt)("p",null,"Read more about the ",(0,r.kt)("a",{parentName:"p",href:"/docs/data-model/prisma-file"},"Prisma Schema File")," and how Wasp uses it to generate the database schema and Prisma client."),(0,r.kt)("p",null,"That's it!"),(0,r.kt)("p",null,"You should now be able to run your app with the new Wasp 0.14.0. We recommend reading through the updated ",(0,r.kt)("a",{parentName:"p",href:"/docs/auth/entities/"},"Accessing User Data")," section to get a better understanding of the new API."))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0245f0fe.8b8a44a2.js b/assets/js/0245f0fe.8b8a44a2.js deleted file mode 100644 index 9ff708821f..0000000000 --- a/assets/js/0245f0fe.8b8a44a2.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[90665],{3905:(e,t,n)=>{n.d(t,{Zo:()=>m,kt:()=>g});var a=n(67294);function r(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 s(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=a.createContext({}),p=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},m=function(e){var t=p(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)}},c=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,l=e.parentName,m=o(e,["components","mdxType","originalType","parentName"]),u=p(n),c=r,g=u["".concat(l,".").concat(c)]||u[c]||d[c]||i;return n?a.createElement(g,s(s({ref:t},m),{},{components:n})):a.createElement(g,s({ref:t},m))}));function g(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,s=new Array(i);s[0]=c;var o={};for(var l in t)hasOwnProperty.call(t,l)&&(o[l]=t[l]);o.originalType=e,o[u]="string"==typeof e?e:r,s[1]=o;for(var p=2;p{n.d(t,{Z:()=>s});var a=n(67294),r=n(86010);const i={tabItem:"tabItem_Ymn6"};function s(e){let{children:t,hidden:n,className:s}=e;return a.createElement("div",{role:"tabpanel",className:(0,r.Z)(i.tabItem,s),hidden:n},t)}},74866:(e,t,n)=>{n.d(t,{Z:()=>v});var a=n(87462),r=n(67294),i=n(86010),s=n(12466),o=n(16550),l=n(91980),p=n(67392),m=n(50012);function u(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??u(n);return function(e){const t=(0,p.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 c(e){let{value:t,tabValues:n}=e;return n.some((e=>e.value===t))}function g(e){let{queryString:t=!1,groupId:n}=e;const a=(0,o.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 h(e){const{defaultValue:t,queryString:n=!1,groupId:a}=e,i=d(e),[s,o]=(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(!c({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,p]=g({queryString:n,groupId:a}),[u,h]=function(e){let{groupId:t}=e;const n=function(e){return e?`docusaurus.tab.${e}`:null}(t),[a,i]=(0,m.Nk)(n);return[a,(0,r.useCallback)((e=>{n&&i.set(e)}),[n,i])]}({groupId:a}),k=(()=>{const e=l??u;return c({value:e,tabValues:i})?e:null})();(0,r.useLayoutEffect)((()=>{k&&o(k)}),[k]);return{selectedValue:s,selectValue:(0,r.useCallback)((e=>{if(!c({value:e,tabValues:i}))throw new Error(`Can't select invalid tab value=${e}`);o(e),p(e),h(e)}),[p,h,i]),tabValues:i}}var k=n(72389);const f={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};function y(e){let{className:t,block:n,selectedValue:o,selectValue:l,tabValues:p}=e;const m=[],{blockElementScrollPositionUntilNextRender:u}=(0,s.o5)(),d=e=>{const t=e.currentTarget,n=m.indexOf(t),a=p[n].value;a!==o&&(u(t),l(a))},c=e=>{let t=null;switch(e.key){case"Enter":d(e);break;case"ArrowRight":{const n=m.indexOf(e.currentTarget)+1;t=m[n]??m[0];break}case"ArrowLeft":{const n=m.indexOf(e.currentTarget)-1;t=m[n]??m[m.length-1];break}}t?.focus()};return r.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,i.Z)("tabs",{"tabs--block":n},t)},p.map((e=>{let{value:t,label:n,attributes:s}=e;return r.createElement("li",(0,a.Z)({role:"tab",tabIndex:o===t?0:-1,"aria-selected":o===t,key:t,ref:e=>m.push(e),onKeyDown:c,onClick:d},s,{className:(0,i.Z)("tabs__item",f.tabItem,s?.className,{"tabs__item--active":o===t})}),n??t)})))}function N(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 b(e){const t=h(e);return r.createElement("div",{className:(0,i.Z)("tabs-container",f.tabList)},r.createElement(y,(0,a.Z)({},e,t)),r.createElement(N,(0,a.Z)({},e,t)))}function v(e){const t=(0,k.Z)();return r.createElement(b,(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("{"),s=t.slice(i+1,t.length-1),[o,l]=s.split(","),p=t.slice(0,i);return a.createElement("code",null,p+("js"===n?o:l))}},85798:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>m,contentTitle:()=>l,default:()=>g,frontMatter:()=>o,metadata:()=>p,toc:()=>u});var a=n(87462),r=(n(67294),n(3905)),i=(n(46300),n(85162)),s=n(74866);const o={title:"Migration from 0.13.X to 0.14.X"},l=void 0,p={unversionedId:"migration-guides/migrate-from-0-13-to-0-14",id:"version-0.15.0/migration-guides/migrate-from-0-13-to-0-14",title:"Migration from 0.13.X to 0.14.X",description:"This guide only covers the migration from 0.13.X to 0.14.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.",source:"@site/versioned_docs/version-0.15.0/migration-guides/migrate-from-0-13-to-0-14.md",sourceDirName:"migration-guides",slug:"/migration-guides/migrate-from-0-13-to-0-14",permalink:"/docs/migration-guides/migrate-from-0-13-to-0-14",draft:!1,editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/versioned_docs/version-0.15.0/migration-guides/migrate-from-0-13-to-0-14.md",tags:[],version:"0.15.0",frontMatter:{title:"Migration from 0.13.X to 0.14.X"},sidebar:"docs",previous:{title:"Migration from 0.14.X to 0.15.X",permalink:"/docs/migration-guides/migrate-from-0-14-to-0-15"},next:{title:"Migration from 0.12.X to 0.13.X",permalink:"/docs/migration-guides/migrate-from-0-12-to-0-13"}},m={},u=[{value:"What's new in 0.14.0?",id:"whats-new-in-0140",level:2},{value:"Using Prisma Schema file directly",id:"using-prisma-schema-file-directly",level:3},{value:"Better auth user API",id:"better-auth-user-api",level:3},{value:"How to migrate?",id:"how-to-migrate",level:2},{value:"Bump the version and update tsconfig.json",id:"bump-the-version-and-update-tsconfigjson",level:3},{value:"Migrate to the new schema.prisma file",id:"migrate-to-the-new-schemaprisma-file",level:3},{value:"Migrate how you access user auth fields",id:"migrate-how-you-access-user-auth-fields",level:3},{value:"Migrate the database",id:"migrate-the-database",level:3}],d={toc:u},c="wrapper";function g(e){let{components:t,...n}=e;return(0,r.kt)(c,(0,a.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("admonition",{title:"Are you on 0.11.X or earlier?",type:"note"},(0,r.kt)("p",{parentName:"admonition"},"This guide only covers the migration from ",(0,r.kt)("strong",{parentName:"p"},"0.13.X to 0.14.X"),". If you are migrating from 0.11.X or earlier, please read the ",(0,r.kt)("a",{parentName:"p",href:"/docs/migration-guides/migrate-from-0-11-to-0-12"},"migration guide from 0.11.X to 0.12.X")," first.")),(0,r.kt)("h2",{id:"whats-new-in-0140"},"What's new in 0.14.0?"),(0,r.kt)("h3",{id:"using-prisma-schema-file-directly"},"Using Prisma Schema file directly"),(0,r.kt)("p",null,"Before 0.14.0, users defined their entities in the ",(0,r.kt)("inlineCode",{parentName:"p"},".wasp")," file, and Wasp generated the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file based on that. This approach had some limitations, and users couldn't use some advanced Prisma features."),(0,r.kt)("p",null,"Wasp now exposes the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file directly to the user. You now define your entities in the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file and Wasp uses that to generate the database schema and Prisma client. You can use all the Prisma features directly in the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file. Simply put, the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file is now the source of truth for your database schema."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.13.0"\n },\n title: "MyApp",\n db: {\n system: PostgreSQL\n },\n}\n\nentity User {=psl\n id Int @id @default(autoincrement())\n tasks Task[]\npsl=}\n\nentity Task {=psl\n id Int @id @default(autoincrement())\n description String\n isDone Boolean\n userId Int\n user User @relation(fields: [userId], references: [id])\npsl=}\n'))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.14.0"\n },\n title: "MyApp",\n}\n')),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "postgresql"\n url = env("DATABASE_URL")\n}\n\ngenerator client {\n provider = "prisma-client-js"\n}\n\nmodel User {\n id Int @id @default(autoincrement())\n tasks Task[]\n}\n\nmodel Task {\n id Int @id @default(autoincrement())\n description String\n isDone Boolean\n userId Int\n user User @relation(fields: [userId], references: [id])\n}\n')))),(0,r.kt)("h3",{id:"better-auth-user-api"},"Better auth user API"),(0,r.kt)("p",null,"Wasp introduced a much simpler API for accessing user auth fields like ",(0,r.kt)("inlineCode",{parentName:"p"},"username"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"email")," or ",(0,r.kt)("inlineCode",{parentName:"p"},"isEmailVerified")," on the ",(0,r.kt)("inlineCode",{parentName:"p"},"user")," object. You don't need to use helper functions every time you want to access the user's ",(0,r.kt)("inlineCode",{parentName:"p"},"username")," or do extra steps to get proper typing."),(0,r.kt)("h2",{id:"how-to-migrate"},"How to migrate?"),(0,r.kt)("p",null,"To migrate your app to Wasp 0.14.x, you must:"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},"Bump the version in ",(0,r.kt)("inlineCode",{parentName:"li"},"main.wasp")," and update your ",(0,r.kt)("inlineCode",{parentName:"li"},"tsconfig.json"),"."),(0,r.kt)("li",{parentName:"ol"},"Migrate your entities into the new ",(0,r.kt)("inlineCode",{parentName:"li"},"schema.prisma")," file."),(0,r.kt)("li",{parentName:"ol"},"Update code that accesses user fields.")),(0,r.kt)("h3",{id:"bump-the-version-and-update-tsconfigjson"},"Bump the version and update ",(0,r.kt)("inlineCode",{parentName:"h3"},"tsconfig.json")),(0,r.kt)("p",null,"Let's start with something simple. Update the version field in your Wasp file to ",(0,r.kt)("inlineCode",{parentName:"p"},"^0.14.0"),":"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app MyApp {\n wasp: {\n // highlight-next-line\n version: "^0.14.0"\n },\n}\n')),(0,r.kt)("p",null,"To ensure your project works correctly with Wasp 0.14.0, you must also update your\n",(0,r.kt)("inlineCode",{parentName:"p"},"tsconfig.json")," file."),(0,r.kt)("p",null,"If you haven't changed anything in your project's ",(0,r.kt)("inlineCode",{parentName:"p"},"tsconfig.json")," file (this is\nthe case for most users), just replace its contents with the new version shown\nbelow."),(0,r.kt)("p",null,"If you have made changes to your ",(0,r.kt)("inlineCode",{parentName:"p"},"tsconfig.json")," file, we recommend taking the\nnew version of the file and reapplying them."),(0,r.kt)("p",null,"Here's the new version of the ",(0,r.kt)("inlineCode",{parentName:"p"},"tsconfig.json")," file:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-json",metastring:"title=tsconfig.json",title:"tsconfig.json"},'// =============================== IMPORTANT =================================\n//\n// This file is only used for Wasp IDE support. You can change it to configure\n// your IDE checks, but none of these options will affect the TypeScript\n// compiler. Proper TS compiler configuration in Wasp is coming soon :)\n{\n "compilerOptions": {\n "module": "esnext",\n "target": "esnext",\n // We\'re bundling all code in the end so this is the most appropriate option,\n // it\'s also important for autocomplete to work properly.\n "moduleResolution": "bundler",\n // JSX support\n "jsx": "preserve",\n "strict": true,\n // Allow default imports.\n "esModuleInterop": true,\n "lib": ["dom", "dom.iterable", "esnext"],\n "allowJs": true,\n "typeRoots": [\n // This is needed to properly support Vitest testing with jest-dom matchers.\n // Types for jest-dom are not recognized automatically and Typescript complains\n // about missing types e.g. when using `toBeInTheDocument` and other matchers.\n "node_modules/@testing-library",\n // Specifying type roots overrides the default behavior of looking at the\n // node_modules/@types folder so we had to list it explicitly.\n // Source 1: https://www.typescriptlang.org/tsconfig#typeRoots\n // Source 2: https://github.com/testing-library/jest-dom/issues/546#issuecomment-1889884843\n "node_modules/@types"\n ],\n // Since this TS config is used only for IDE support and not for\n // compilation, the following directory doesn\'t exist. We need to specify\n // it to prevent this error:\n // https://stackoverflow.com/questions/42609768/typescript-error-cannot-write-file-because-it-would-overwrite-input-file\n "outDir": ".wasp/phantom"\n }\n}\n')),(0,r.kt)("h3",{id:"migrate-to-the-new-schemaprisma-file"},"Migrate to the new ",(0,r.kt)("inlineCode",{parentName:"h3"},"schema.prisma")," file"),(0,r.kt)("p",null,"To use the new ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file, you need to move your entities from the ",(0,r.kt)("inlineCode",{parentName:"p"},".wasp")," file to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file."),(0,r.kt)("p",null,"1","."," ",(0,r.kt)("strong",{parentName:"p"},"Create a new ",(0,r.kt)("inlineCode",{parentName:"strong"},"schema.prisma")," file")),(0,r.kt)("p",null,"Create a new file named ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," in the root of your project:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-c"},".\n\u251c\u2500\u2500 main.wasp\n...\n// highlight-next-line\n\u251c\u2500\u2500 schema.prisma\n\u251c\u2500\u2500 src\n\u251c\u2500\u2500 tsconfig.json\n\u2514\u2500\u2500 vite.config.ts\n")),(0,r.kt)("p",null,"2","."," ",(0,r.kt)("strong",{parentName:"p"},"Add the ",(0,r.kt)("inlineCode",{parentName:"strong"},"datasource")," block")," to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file"),(0,r.kt)("p",null,"This block specifies the database type and connection URL:"),(0,r.kt)(s.Z,{groupId:"db",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"sqlite",label:"Sqlite",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "sqlite"\n url = env("DATABASE_URL")\n}\n'))),(0,r.kt)(i.Z,{value:"postgresql",label:"PostgreSQL",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "postgresql"\n url = env("DATABASE_URL")\n}\n')))),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"The ",(0,r.kt)("inlineCode",{parentName:"p"},"provider")," should be either ",(0,r.kt)("inlineCode",{parentName:"p"},'"postgresql"')," or ",(0,r.kt)("inlineCode",{parentName:"p"},'"sqlite"'),".")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"The ",(0,r.kt)("inlineCode",{parentName:"p"},"url")," must be set to ",(0,r.kt)("inlineCode",{parentName:"p"},'env("DATABASE_URL")')," so that Wasp can inject the database URL from the environment variables."))),(0,r.kt)("p",null,"3","."," ",(0,r.kt)("strong",{parentName:"p"},"Add the ",(0,r.kt)("inlineCode",{parentName:"strong"},"generator")," block")," to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file"),(0,r.kt)("p",null,"This block specifies the Prisma Client generator Wasp uses:"),(0,r.kt)(s.Z,{groupId:"db",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"sqlite",label:"Sqlite",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "sqlite"\n url = env("DATABASE_URL")\n}\n\n// highlight-start\ngenerator client {\n provider = "prisma-client-js"\n}\n// highlight-end\n'))),(0,r.kt)(i.Z,{value:"postgresql",label:"PostgreSQL",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "postgresql"\n url = env("DATABASE_URL")\n}\n\n// highlight-start\ngenerator client {\n provider = "prisma-client-js"\n}\n// highlight-end\n')))),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"The ",(0,r.kt)("inlineCode",{parentName:"li"},"provider")," should be set to ",(0,r.kt)("inlineCode",{parentName:"li"},'"prisma-client-js"'),".")),(0,r.kt)("p",null,"4","."," ",(0,r.kt)("strong",{parentName:"p"},"Move your entities")," to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file"),(0,r.kt)("p",null,"Move the entities from the ",(0,r.kt)("inlineCode",{parentName:"p"},".wasp")," file to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file:"),(0,r.kt)(s.Z,{groupId:"db",mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"sqlite",label:"Sqlite",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "sqlite"\n url = env("DATABASE_URL")\n}\n\ngenerator client {\n provider = "prisma-client-js"\n}\n\n// There are some example entities, you should move your entities here\n// highlight-start\nmodel User {\n id Int @id @default(autoincrement())\n tasks Task[]\n}\n\nmodel Task {\n id Int @id @default(autoincrement())\n description String\n isDone Boolean\n userId Int\n user User @relation(fields: [userId], references: [id])\n}\n// highlight-end\n'))),(0,r.kt)(i.Z,{value:"postgresql",label:"PostgreSQL",mdxType:"TabItem"},(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "postgresql"\n url = env("DATABASE_URL")\n}\n\ngenerator client {\n provider = "prisma-client-js"\n}\n\n// There are some example entities, you should move your entities here\n// highlight-start\nmodel User {\n id Int @id @default(autoincrement())\n tasks Task[]\n}\n\nmodel Task {\n id Int @id @default(autoincrement())\n description String\n isDone Boolean\n userId Int\n user User @relation(fields: [userId], references: [id])\n}\n// highlight-end\n')))),(0,r.kt)("p",null,"When moving the entities over, you'll need to change ",(0,r.kt)("inlineCode",{parentName:"p"},"entity")," to ",(0,r.kt)("inlineCode",{parentName:"p"},"model")," and remove the ",(0,r.kt)("inlineCode",{parentName:"p"},"=psl")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"psl=")," tags."),(0,r.kt)("p",null,"If you had the following in the ",(0,r.kt)("inlineCode",{parentName:"p"},".wasp")," file:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},"entity Task {=psl\n // Stays the same\npsl=}\n")),(0,r.kt)("p",null,"... it would look like this in the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},"model Task {\n // Stays the same\n}\n")),(0,r.kt)("p",null,"5","."," ",(0,r.kt)("strong",{parentName:"p"},"Remove ",(0,r.kt)("inlineCode",{parentName:"strong"},"app.db.system"))," field from the Wasp file"),(0,r.kt)("p",null,"We now configure the DB system in the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file, so there is no need for that field in the Wasp file."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},"app MyApp {\n // ...\n db: {\n // highlight-next-line\n system: PostgreSQL,\n }\n}\n")),(0,r.kt)("p",null,"6","."," ",(0,r.kt)("strong",{parentName:"p"},"Migrate Prisma preview features config")," to the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file"),(0,r.kt)("p",null,"If you didn't use any Prisma preview features, you can skip this step."),(0,r.kt)("p",null,"If you had the following in the ",(0,r.kt)("inlineCode",{parentName:"p"},".wasp")," file:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app MyApp {\n // ...\n db: {\n // highlight-start\n prisma: {\n clientPreviewFeatures: ["postgresqlExtensions"]\n dbExtensions: [\n { name: "hstore", schema: "myHstoreSchema" },\n { name: "pg_trgm" },\n { name: "postgis", version: "2.1" },\n ]\n }\n // highlight-end\n }\n}\n')),(0,r.kt)("p",null,"... it will become this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},'datasource db {\n provider = "postgresql"\n url = env("DATABASE_URL")\n // highlight-next-line\n extensions = [hstore(schema: "myHstoreSchema"), pg_trgm, postgis(version: "2.1")]\n}\n\ngenerator client {\n provider = "prisma-client-js"\n // highlight-next-line\n previewFeatures = ["postgresqlExtensions"]\n}\n')),(0,r.kt)("p",null,"All that's left to do is migrate the database."),(0,r.kt)("p",null,"To avoid type errors, it's best to take care of database migrations after you've migrated the rest of the code.\nSo, just keep reading, and we will remind you to migrate the database as ",(0,r.kt)("a",{parentName:"p",href:"#migrate-the-database"},"the last step of the migration guide"),"."),(0,r.kt)("p",null,"Read more about the ",(0,r.kt)("a",{parentName:"p",href:"/docs/data-model/prisma-file"},"Prisma Schema File")," and how Wasp uses it to generate the database schema and Prisma client."),(0,r.kt)("h3",{id:"migrate-how-you-access-user-auth-fields"},"Migrate how you access user auth fields"),(0,r.kt)("p",null,"We had to make a couple of breaking changes to reach the new simpler API."),(0,r.kt)("p",null,"Follow the steps below to migrate:"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Replace the ",(0,r.kt)("inlineCode",{parentName:"strong"},"getUsername")," helper")," with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities.username.id")),(0,r.kt)("p",{parentName:"li"},"If you didn't use the ",(0,r.kt)("inlineCode",{parentName:"p"},"getUsername")," helper in your code, you can skip this step."),(0,r.kt)("p",{parentName:"li"},"This helper changed and it no longer works with the ",(0,r.kt)("inlineCode",{parentName:"p"},"user")," you receive as a prop on a page or through the ",(0,r.kt)("inlineCode",{parentName:"p"},"context"),". You'll need to replace it with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities.username.id"),"."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { getUsername, AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const username = getUsername(user)\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"import { getUsername } from 'wasp/auth'\n\nexport const createTask: CreateTask<...> = async (args, context) => {\n const username = getUsername(context.user)\n // ...\n}\n"))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const username = user.identities.username?.id\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"export const createTask: CreateTask<...> = async (args, context) => {\n const username = context.user.identities.username?.id\n // ...\n}\n"))))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Replace the ",(0,r.kt)("inlineCode",{parentName:"strong"},"getEmail")," helper")," with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities.email.id")),(0,r.kt)("p",{parentName:"li"},"If you didn't use the ",(0,r.kt)("inlineCode",{parentName:"p"},"getEmail")," helper in your code, you can skip this step."),(0,r.kt)("p",{parentName:"li"},"This helper changed and it no longer works with the ",(0,r.kt)("inlineCode",{parentName:"p"},"user")," you receive as a prop on a page or through the ",(0,r.kt)("inlineCode",{parentName:"p"},"context"),". You'll need to replace it with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities.email.id"),"."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { getEmail, AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const email = getEmail(user)\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"import { getEmail } from 'wasp/auth'\n\nexport const createTask: CreateTask<...> = async (args, context) => {\n const email = getEmail(context.user)\n // ...\n}\n"))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const email = user.identities.email?.id\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"export const createTask: CreateTask<...> = async (args, context) => {\n const email = context.user.identities.email?.id\n // ...\n}\n"))))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Replace accessing ",(0,r.kt)("inlineCode",{parentName:"strong"},"providerData"))," with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities..")),(0,r.kt)("p",{parentName:"li"},"If you didn't use any data from the ",(0,r.kt)("inlineCode",{parentName:"p"},"providerData")," object, you can skip this step."),(0,r.kt)("p",{parentName:"li"},"Replace ",(0,r.kt)("inlineCode",{parentName:"p"},"")," with the provider name (for example ",(0,r.kt)("inlineCode",{parentName:"p"},"username"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"email"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"google"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"github"),", etc.) and ",(0,r.kt)("inlineCode",{parentName:"p"},"")," with the field you want to access (for example ",(0,r.kt)("inlineCode",{parentName:"p"},"isEmailVerified"),")."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { findUserIdentity, AuthUser } from 'wasp/auth'\n\nfunction getProviderData(user: AuthUser) {\n const emailIdentity = findUserIdentity(user, 'email')\n // We needed this before check for proper type support\n return emailIdentity && 'isEmailVerified' in emailIdentity.providerData\n ? emailIdentity.providerData\n : null\n}\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const providerData = getProviderData(user)\n const isEmailVerified = providerData ? providerData.isEmailVerified : null\n // ...\n}\n"))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n // The email object is properly typed, so we can access `isEmailVerified` directly\n const isEmailVerified = user.identities.email?.isEmailVerified\n // ...\n}\n"))))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Use ",(0,r.kt)("inlineCode",{parentName:"strong"},"getFirstProviderUserId")," directly")," on the user object"),(0,r.kt)("p",{parentName:"li"},"If you didn't use ",(0,r.kt)("inlineCode",{parentName:"p"},"getFirstProviderUserId")," in your code, you can skip this step."),(0,r.kt)("p",{parentName:"li"},"You should replace ",(0,r.kt)("inlineCode",{parentName:"p"},"getFirstProviderUserId(user)")," with ",(0,r.kt)("inlineCode",{parentName:"p"},"user.getFirstProviderUserId()"),"."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { getFirstProviderUserId, AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const userId = getFirstProviderUserId(user)\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"import { getFirstProviderUserId } from 'wasp/auth'\n\nexport const createTask: CreateTask<...> = async (args, context) => {\n const userId = getFirstProviderUserId(context.user)\n // ...\n}\n"))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const userId = user.getFirstProviderUserId()\n // ...\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"export const createTask: CreateTask<...> = async (args, context) => {\n const userId = user.getFirstProviderUserId()\n // ...\n}\n"))))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Replace ",(0,r.kt)("inlineCode",{parentName:"strong"},"findUserIdentity"))," with checks on ",(0,r.kt)("inlineCode",{parentName:"p"},"user.identities.")),(0,r.kt)("p",{parentName:"li"},"If you didn't use ",(0,r.kt)("inlineCode",{parentName:"p"},"findUserIdentity")," in your code, you can skip this step."),(0,r.kt)("p",{parentName:"li"},"Instead of using ",(0,r.kt)("inlineCode",{parentName:"p"},"findUserIdentity")," to get the identity object, you can directly check if the identity exists on the ",(0,r.kt)("inlineCode",{parentName:"p"},"identities")," object."),(0,r.kt)(s.Z,{mdxType:"Tabs"},(0,r.kt)(i.Z,{value:"before",label:"Before",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { findUserIdentity, AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n const usernameIdentity = findUserIdentity(user, 'username')\n if (usernameIdentity) {\n // ...\n }\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"import { findUserIdentity } from 'wasp/auth'\n\nexport const createTask: CreateTask<...> = async (args, context) => {\n const usernameIdentity = findUserIdentity(context.user, 'username')\n if (usernameIdentity) {\n // ...\n }\n}\n"))),(0,r.kt)(i.Z,{value:"after",label:"After",mdxType:"TabItem"},(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/MainPage.tsx"',title:'"src/MainPage.tsx"'},"import { AuthUser } from 'wasp/auth'\n\nconst MainPage = ({ user }: { user: AuthUser }) => {\n if (user.identities.username) {\n // ...\n }\n}\n")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/tasks.ts",title:"src/tasks.ts"},"export const createTask: CreateTask<...> = async (args, context) => {\n if (context.user.identities.username) {\n // ...\n }\n}\n")))))),(0,r.kt)("h3",{id:"migrate-the-database"},"Migrate the database"),(0,r.kt)("p",null,"Finally, you can ",(0,r.kt)("strong",{parentName:"p"},"Run the Wasp CLI")," to regenerate the new Prisma client:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"wasp db migrate-dev\n")),(0,r.kt)("p",null,"This command generates the Prisma client based on the ",(0,r.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file."),(0,r.kt)("p",null,"Read more about the ",(0,r.kt)("a",{parentName:"p",href:"/docs/data-model/prisma-file"},"Prisma Schema File")," and how Wasp uses it to generate the database schema and Prisma client."),(0,r.kt)("p",null,"That's it!"),(0,r.kt)("p",null,"You should now be able to run your app with the new Wasp 0.14.0. We recommend reading through the updated ",(0,r.kt)("a",{parentName:"p",href:"/docs/auth/entities/"},"Accessing User Data")," section to get a better understanding of the new API."))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/045ac00a.54569709.js b/assets/js/045ac00a.942c64b8.js similarity index 98% rename from assets/js/045ac00a.54569709.js rename to assets/js/045ac00a.942c64b8.js index 9fad51c8dc..efd9556696 100644 --- a/assets/js/045ac00a.54569709.js +++ b/assets/js/045ac00a.942c64b8.js @@ -1 +1 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[70018],{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(16726).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},16726:(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([[70018],{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(27961).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},27961:(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/052d35c1.8e0c80b8.js b/assets/js/052d35c1.31122a54.js similarity index 99% rename from assets/js/052d35c1.8e0c80b8.js rename to assets/js/052d35c1.31122a54.js index c69f754bc8..249e6d772d 100644 --- a/assets/js/052d35c1.8e0c80b8.js +++ b/assets/js/052d35c1.31122a54.js @@ -1 +1 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[61150],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>h});var a=n(67294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(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 o(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var l=a.createContext({}),u=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):o(o({},t),e)),n},p=function(e){var t=u(e.components);return a.createElement(l.Provider,{value:t},e.children)},d="mdxType",c={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,i=e.mdxType,r=e.originalType,l=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),d=u(n),m=i,h=d["".concat(l,".").concat(m)]||d[m]||c[m]||r;return n?a.createElement(h,o(o({ref:t},p),{},{components:n})):a.createElement(h,o({ref:t},p))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=n.length,o=new Array(r);o[0]=m;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[d]="string"==typeof e?e:i,o[1]=s;for(var u=2;u{n.d(t,{Z:()=>o});var a=n(67294),i=n(86010);const r={tabItem:"tabItem_Ymn6"};function o(e){let{children:t,hidden:n,className:o}=e;return a.createElement("div",{role:"tabpanel",className:(0,i.Z)(r.tabItem,o),hidden:n},t)}},74866:(e,t,n)=>{n.d(t,{Z:()=>N});var a=n(87462),i=n(67294),r=n(86010),o=n(12466),s=n(16550),l=n(91980),u=n(67392),p=n(50012);function d(e){return function(e){return i.Children.map(e,(e=>{if(!e||(0,i.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:i}}=e;return{value:t,label:n,attributes:a,default:i}}))}function c(e){const{values:t,children:n}=e;return(0,i.useMemo)((()=>{const e=t??d(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 h(e){let{queryString:t=!1,groupId:n}=e;const a=(0,s.k6)(),r=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)(r),(0,i.useCallback)((e=>{if(!r)return;const t=new URLSearchParams(a.location.search);t.set(r,e),a.replace({...a.location,search:t.toString()})}),[r,a])]}function g(e){const{defaultValue:t,queryString:n=!1,groupId:a}=e,r=c(e),[o,s]=(0,i.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:r}))),[l,u]=h({queryString:n,groupId:a}),[d,g]=function(e){let{groupId:t}=e;const n=function(e){return e?`docusaurus.tab.${e}`:null}(t),[a,r]=(0,p.Nk)(n);return[a,(0,i.useCallback)((e=>{n&&r.set(e)}),[n,r])]}({groupId:a}),f=(()=>{const e=l??d;return m({value:e,tabValues:r})?e:null})();(0,i.useLayoutEffect)((()=>{f&&s(f)}),[f]);return{selectedValue:o,selectValue:(0,i.useCallback)((e=>{if(!m({value:e,tabValues:r}))throw new Error(`Can't select invalid tab value=${e}`);s(e),u(e),g(e)}),[u,g,r]),tabValues:r}}var f=n(72389);const k={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};function b(e){let{className:t,block:n,selectedValue:s,selectValue:l,tabValues:u}=e;const p=[],{blockElementScrollPositionUntilNextRender:d}=(0,o.o5)(),c=e=>{const t=e.currentTarget,n=p.indexOf(t),a=u[n].value;a!==s&&(d(t),l(a))},m=e=>{let t=null;switch(e.key){case"Enter":c(e);break;case"ArrowRight":{const n=p.indexOf(e.currentTarget)+1;t=p[n]??p[0];break}case"ArrowLeft":{const n=p.indexOf(e.currentTarget)-1;t=p[n]??p[p.length-1];break}}t?.focus()};return i.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,r.Z)("tabs",{"tabs--block":n},t)},u.map((e=>{let{value:t,label:n,attributes:o}=e;return i.createElement("li",(0,a.Z)({role:"tab",tabIndex:s===t?0:-1,"aria-selected":s===t,key:t,ref:e=>p.push(e),onKeyDown:m,onClick:c},o,{className:(0,r.Z)("tabs__item",k.tabItem,o?.className,{"tabs__item--active":s===t})}),n??t)})))}function y(e){let{lazy:t,children:n,selectedValue:a}=e;const r=(Array.isArray(n)?n:[n]).filter(Boolean);if(t){const e=r.find((e=>e.props.value===a));return e?(0,i.cloneElement)(e,{className:"margin-top--md"}):null}return i.createElement("div",{className:"margin-top--md"},r.map(((e,t)=>(0,i.cloneElement)(e,{key:t,hidden:e.props.value!==a}))))}function v(e){const t=g(e);return i.createElement("div",{className:(0,r.Z)("tabs-container",k.tabList)},i.createElement(b,(0,a.Z)({},e,t)),i.createElement(y,(0,a.Z)({},e,t)))}function N(e){const t=(0,f.Z)();return i.createElement(v,(0,a.Z)({key:String(t)},e))}},46300:(e,t,n)=>{n.d(t,{Z:()=>r});var a=n(67294),i=n(50012);function r(e){let{path:t}=e;const[n]=(0,i.Nk)("docusaurus.tab.js-ts"),r=t.lastIndexOf("{"),o=t.slice(r+1,t.length-1),[s,l]=o.split(","),u=t.slice(0,r);return a.createElement("code",null,u+("js"===n?s:l))}},46620:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("small",null,(0,i.kt)("p",null,"Read more about accessing the user data in the ",(0,i.kt)("a",{parentName:"p",href:"/docs/auth/entities/#accessing-the-auth-fields"},"Accessing User Data")," section of the docs.")))}s.isMDXComponent=!0},36318:(e,t,n)=>{n.d(t,{ZP:()=>u});var a=n(87462),i=(n(67294),n(3905)),r=(n(46300),n(85162)),o=n(74866);const s={toc:[]},l="wrapper";function u(e){let{components:t,...n}=e;return(0,i.kt)(l,(0,a.Z)({},s,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields")," defines all the extra fields that need to be set on the ",(0,i.kt)("inlineCode",{parentName:"p"},"User")," during the sign-up process. For example, if you have ",(0,i.kt)("inlineCode",{parentName:"p"},"address")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"phone")," fields on your ",(0,i.kt)("inlineCode",{parentName:"p"},"User")," entity, you can set them by defining the ",(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields")," like this:"),(0,i.kt)(o.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(r.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/auth.js"',title:'"src/auth.js"'},"import { defineUserSignupFields } from 'wasp/server/auth'\n\nexport const userSignupFields = defineUserSignupFields({\n address: (data) => {\n if (!data.address) {\n throw new Error('Address is required')\n }\n return data.address\n }\n phone: (data) => data.phone,\n})\n"))),(0,i.kt)(r.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/auth.ts"',title:'"src/auth.ts"'},"import { defineUserSignupFields } from 'wasp/server/auth'\n\nexport const userSignupFields = defineUserSignupFields({\n address: (data) => {\n if (!data.address) {\n throw new Error('Address is required')\n }\n return data.address\n }\n phone: (data) => data.phone,\n})\n")))))}u.isMDXComponent=!0},35208:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-ts"},'const githubIdentity = user.identities.github\n\n// GitHub User ID for example "12345678"\ngithubIdentity.id\n')))}s.isMDXComponent=!0},24373:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"Provider-specific behavior comes down to implementing two functions."),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"configFn")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"userSignupFields"))),(0,i.kt)("p",null,"The reference shows how to define both."),(0,i.kt)("p",null,"For behavior common to all providers, check the general ",(0,i.kt)("a",{parentName:"p",href:"/docs/auth/overview#api-reference"},"API Reference"),"."))}s.isMDXComponent=!0},34626:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"When a user ",(0,i.kt)("strong",{parentName:"p"},"signs in for the first time"),", Wasp creates a new user account and links it to the chosen auth provider account for future logins."))}s.isMDXComponent=!0},63785:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"Wasp automatically generates the ",(0,i.kt)("inlineCode",{parentName:"p"},"defineUserSignupFields")," function to help you correctly type your ",(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields")," object."))}s.isMDXComponent=!0},40971:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"When a user logs in using a social login provider, the backend receives some data about the user.\nWasp lets you access this data inside the ",(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields")," getters."),(0,i.kt)("p",null,"For example, the User entity can include a ",(0,i.kt)("inlineCode",{parentName:"p"},"displayName")," field which you can set based on the details received from the provider."),(0,i.kt)("p",null,"Wasp also lets you customize the configuration of the providers' settings using the ",(0,i.kt)("inlineCode",{parentName:"p"},"configFn")," function."),(0,i.kt)("p",null,"Let's use this example to show both fields in action:"))}s.isMDXComponent=!0},10769:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"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."),(0,i.kt)("p",null,"There are two mechanisms used for overriding the default behavior:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"userSignupFields")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"configFn"))),(0,i.kt)("p",null,"Let's explore them in more detail."))}s.isMDXComponent=!0},75801:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"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 ",(0,i.kt)("a",{parentName:"p",href:"../../auth/overview"},"using auth"),"."))}s.isMDXComponent=!0},79780:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"Here's a skeleton of how our ",(0,i.kt)("inlineCode",{parentName:"p"},"main.wasp")," should look like after we're done:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},"// Configuring the social authentication\napp myApp {\n auth: { ... }\n}\n\n// Defining routes and pages\nroute LoginRoute { ... }\npage LoginPage { ... }\n")))}s.isMDXComponent=!0},20955:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>w,contentTitle:()=>v,default:()=>A,frontMatter:()=>y,metadata:()=>N,toc:()=>x});var a=n(87462),i=(n(67294),n(3905)),r=n(46300),o=n(85162),s=n(74866),l=n(44996),u=n(34626),p=n(10769),d=n(40971),c=n(75801),m=n(79780),h=n(63785),g=n(24373),f=n(36318),k=n(35208),b=n(46620);const y={title:"GitHub"},v=void 0,N={unversionedId:"auth/social-auth/github",id:"version-0.15.0/auth/social-auth/github",title:"GitHub",description:"Wasp supports Github Authentication out of the box.",source:"@site/versioned_docs/version-0.15.0/auth/social-auth/github.md",sourceDirName:"auth/social-auth",slug:"/auth/social-auth/github",permalink:"/docs/auth/social-auth/github",draft:!1,editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/versioned_docs/version-0.15.0/auth/social-auth/github.md",tags:[],version:"0.15.0",frontMatter:{title:"GitHub"},sidebar:"docs",previous:{title:"Overview",permalink:"/docs/auth/social-auth/overview"},next:{title:"Google",permalink:"/docs/auth/social-auth/google"}},w={},x=[{value:"Setting up Github Auth",id:"setting-up-github-auth",level:2},{value:"1. Adding Github Auth to Your Wasp File",id:"1-adding-github-auth-to-your-wasp-file",level:3},{value:"2. Add the User Entity",id:"2-add-the-user-entity",level:3},{value:"3. Creating a GitHub OAuth App",id:"3-creating-a-github-oauth-app",level:3},{value:"4. Adding Environment Variables",id:"4-adding-environment-variables",level:3},{value:"5. Adding the Necessary Routes and Pages",id:"5-adding-the-necessary-routes-and-pages",level:3},{value:"6. Creating the Client Pages",id:"6-creating-the-client-pages",level:3},{value:"Conclusion",id:"conclusion",level:3},{value:"Default Behaviour",id:"default-behaviour",level:2},{value:"Overrides",id:"overrides",level:2},{value:"Data Received From GitHub",id:"data-received-from-github",level:3},{value:"Using the Data Received From GitHub",id:"using-the-data-received-from-github",level:3},{value:"Using Auth",id:"using-auth",level:2},{value:"API Reference",id:"api-reference",level:2}],T={toc:x},C="wrapper";function A(e){let{components:t,...y}=e;return(0,i.kt)(C,(0,a.Z)({},T,y,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"Wasp supports Github Authentication out of the box.\nGitHub is a great external auth choice when you're building apps for developers, as most of them already have a GitHub account."),(0,i.kt)("p",null,"Letting your users log in using their GitHub accounts turns the signup process into a breeze."),(0,i.kt)("p",null,"Let's walk through enabling Github Authentication, explain some of the default settings, and show how to override them."),(0,i.kt)("h2",{id:"setting-up-github-auth"},"Setting up Github Auth"),(0,i.kt)("p",null,"Enabling GitHub Authentication comes down to a series of steps:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Enabling GitHub authentication in the Wasp file."),(0,i.kt)("li",{parentName:"ol"},"Adding the ",(0,i.kt)("inlineCode",{parentName:"li"},"User")," entity."),(0,i.kt)("li",{parentName:"ol"},"Creating a GitHub OAuth app."),(0,i.kt)("li",{parentName:"ol"},"Adding the necessary Routes and Pages"),(0,i.kt)("li",{parentName:"ol"},"Using Auth UI components in our Pages.")),(0,i.kt)(m.ZP,{mdxType:"WaspFileStructureNote"}),(0,i.kt)("h3",{id:"1-adding-github-auth-to-your-wasp-file"},"1. Adding Github Auth to Your Wasp File"),(0,i.kt)("p",null,"Let's start by properly configuring the Auth object:"),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n // highlight-next-line\n // 1. Specify the User entity (we\'ll define it next)\n // highlight-next-line\n userEntity: User,\n methods: {\n // highlight-next-line\n // 2. Enable Github Auth\n // highlight-next-line\n gitHub: {}\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n'))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n // highlight-next-line\n // 1. Specify the User entity (we\'ll define it next)\n // highlight-next-line\n userEntity: User,\n methods: {\n // highlight-next-line\n // 2. Enable Github Auth\n // highlight-next-line\n gitHub: {}\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n')))),(0,i.kt)("h3",{id:"2-add-the-user-entity"},"2. Add the User Entity"),(0,i.kt)("p",null,"Let's now define the ",(0,i.kt)("inlineCode",{parentName:"p"},"app.auth.userEntity")," entity in the ",(0,i.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file:"),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},"// 3. Define the user entity\nmodel User {\n // highlight-next-line\n id Int @id @default(autoincrement())\n // Add your own fields below\n // ...\n}\n"))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},"// 3. Define the user entity\nmodel User {\n // highlight-next-line\n id Int @id @default(autoincrement())\n // Add your own fields below\n // ...\n}\n")))),(0,i.kt)("h3",{id:"3-creating-a-github-oauth-app"},"3. Creating a GitHub OAuth App"),(0,i.kt)("p",null,"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:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Log into your GitHub account and navigate to: ",(0,i.kt)("a",{parentName:"li",href:"https://github.com/settings/developers"},"https://github.com/settings/developers"),"."),(0,i.kt)("li",{parentName:"ol"},"Select ",(0,i.kt)("strong",{parentName:"li"},"New OAuth App"),"."),(0,i.kt)("li",{parentName:"ol"},"Supply required information.")),(0,i.kt)("img",{alt:"GitHub Applications Screenshot",src:(0,l.Z)("img/integrations-github-1.png"),width:"400px"}),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"For ",(0,i.kt)("strong",{parentName:"li"},"Authorization callback URL"),":",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"For development, put: ",(0,i.kt)("inlineCode",{parentName:"li"},"http://localhost:3001/auth/github/callback"),"."),(0,i.kt)("li",{parentName:"ul"},"Once you know on which URL your API server will be deployed, you can create a new app with that URL instead e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"https://your-server-url.com/auth/github/callback"),".")))),(0,i.kt)("ol",{start:4},(0,i.kt)("li",{parentName:"ol"},"Hit ",(0,i.kt)("strong",{parentName:"li"},"Register application"),"."),(0,i.kt)("li",{parentName:"ol"},"Hit ",(0,i.kt)("strong",{parentName:"li"},"Generate a new client secret")," on the next page."),(0,i.kt)("li",{parentName:"ol"},"Copy your Client ID and Client secret as you'll need them in the next step.")),(0,i.kt)("h3",{id:"4-adding-environment-variables"},"4. Adding Environment Variables"),(0,i.kt)("p",null,"Add these environment variables to the ",(0,i.kt)("inlineCode",{parentName:"p"},".env.server")," file at the root of your project (take their values from the previous step):"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash",metastring:'title=".env.server"',title:'".env.server"'},"GITHUB_CLIENT_ID=your-github-client-id\nGITHUB_CLIENT_SECRET=your-github-client-secret\n")),(0,i.kt)("h3",{id:"5-adding-the-necessary-routes-and-pages"},"5. Adding the Necessary Routes and Pages"),(0,i.kt)("p",null,"Let's define the necessary authentication Routes and Pages."),(0,i.kt)("p",null,"Add the following code to your ",(0,i.kt)("inlineCode",{parentName:"p"},"main.wasp")," file:"),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'// ...\n\nroute LoginRoute { path: "/login", to: LoginPage }\npage LoginPage {\n component: import { Login } from "@src/pages/auth.jsx"\n}\n'))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'// ...\n\nroute LoginRoute { path: "/login", to: LoginPage }\npage LoginPage {\n component: import { Login } from "@src/pages/auth.tsx"\n}\n')))),(0,i.kt)("p",null,"We'll define the React components for these pages in the ",(0,i.kt)(r.Z,{path:"src/pages/auth.{jsx,tsx}",mdxType:"FileExtSwitcher"})," file below."),(0,i.kt)("h3",{id:"6-creating-the-client-pages"},"6. Creating the Client Pages"),(0,i.kt)("admonition",{type:"info"},(0,i.kt)("p",{parentName:"admonition"},"We are using ",(0,i.kt)("a",{parentName:"p",href:"https://tailwindcss.com/"},"Tailwind CSS")," to style the pages. Read more about how to add it ",(0,i.kt)("a",{parentName:"p",href:"../../project/css-frameworks"},"here"),".")),(0,i.kt)("p",null,"Let's create a ",(0,i.kt)(r.Z,{path:"auth.{jsx,tsx}",mdxType:"FileExtSwitcher"})," file in the ",(0,i.kt)("inlineCode",{parentName:"p"},"src/pages")," folder and add the following to it:"),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/pages/auth.jsx"',title:'"src/pages/auth.jsx"'},'import { LoginForm } from \'wasp/client/auth\'\n\nexport function Login() {\n return (\n \n \n \n )\n}\n\n// A layout component to center the content\nexport function Layout({ children }) {\n return (\n
\n
\n
\n
{children}
\n
\n
\n
\n )\n}\n'))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/pages/auth.tsx"',title:'"src/pages/auth.tsx"'},'import { LoginForm } from \'wasp/client/auth\'\n\nexport function Login() {\n return (\n \n \n \n )\n}\n\n// A layout component to center the content\nexport function Layout({ children }: { children: React.ReactNode }) {\n return (\n
\n
\n
\n
{children}
\n
\n
\n
\n )\n}\n')))),(0,i.kt)("p",null,"We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components ",(0,i.kt)("a",{parentName:"p",href:"../../auth/ui"},"here"),"."),(0,i.kt)("h3",{id:"conclusion"},"Conclusion"),(0,i.kt)("p",null,"Yay, we've successfully set up Github Auth! \ud83c\udf89"),(0,i.kt)("p",null,(0,i.kt)("img",{alt:"Github Auth",src:n(29240).Z,width:"1315",height:"800"})),(0,i.kt)("p",null,"Running ",(0,i.kt)("inlineCode",{parentName:"p"},"wasp db migrate-dev")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"wasp start")," should now give you a working app with authentication.\nTo see how to protect specific pages (i.e., hide them from non-authenticated users), read the docs on ",(0,i.kt)("a",{parentName:"p",href:"../../auth/overview"},"using auth"),"."),(0,i.kt)("h2",{id:"default-behaviour"},"Default Behaviour"),(0,i.kt)("p",null,"Add ",(0,i.kt)("inlineCode",{parentName:"p"},"gitHub: {}")," to the ",(0,i.kt)("inlineCode",{parentName:"p"},"auth.methods")," dictionary to use it with default settings."),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:"title=main.wasp",title:"main.wasp"},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n // highlight-next-line\n gitHub: {}\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n'))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:"title=main.wasp",title:"main.wasp"},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n // highlight-next-line\n gitHub: {}\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n')))),(0,i.kt)(u.ZP,{mdxType:"DefaultBehaviour"}),(0,i.kt)("h2",{id:"overrides"},"Overrides"),(0,i.kt)(p.ZP,{mdxType:"OverrideIntro"}),(0,i.kt)("h3",{id:"data-received-from-github"},"Data Received From GitHub"),(0,i.kt)("p",null,"We are using GitHub's API and its ",(0,i.kt)("inlineCode",{parentName:"p"},"/user")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"/user/emails")," endpoints to get the user data."),(0,i.kt)("admonition",{title:"We combine the data from the two endpoints",type:"info"},(0,i.kt)("p",{parentName:"admonition"},"You'll find the emails in the ",(0,i.kt)("inlineCode",{parentName:"p"},"emails")," property in the object that you receive in ",(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields"),"."),(0,i.kt)("p",{parentName:"admonition"},"This is because we combine the data from the ",(0,i.kt)("inlineCode",{parentName:"p"},"/user")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"/user/emails")," endpoints ",(0,i.kt)("strong",{parentName:"p"},"if the ",(0,i.kt)("inlineCode",{parentName:"strong"},"user")," or ",(0,i.kt)("inlineCode",{parentName:"strong"},"user:email")," scope is requested."))),(0,i.kt)("p",null,"The data we receive from GitHub on the ",(0,i.kt)("inlineCode",{parentName:"p"},"/user")," endpoint looks something this:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-json"},'{\n "login": "octocat",\n "id": 1,\n "name": "monalisa octocat",\n "avatar_url": "https://github.com/images/error/octocat_happy.gif",\n "gravatar_id": ""\n // ...\n}\n')),(0,i.kt)("p",null,"And the data from the ",(0,i.kt)("inlineCode",{parentName:"p"},"/user/emails")," endpoint looks something like this:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-json"},'[\n {\n "email": "octocat@github.com",\n "verified": true,\n "primary": true,\n "visibility": "public"\n }\n]\n')),(0,i.kt)("p",null,"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 ",(0,i.kt)("inlineCode",{parentName:"p"},"user")," or ",(0,i.kt)("inlineCode",{parentName:"p"},"user:email")," scope in the ",(0,i.kt)("inlineCode",{parentName:"p"},"configFn")," function."),(0,i.kt)("small",null,(0,i.kt)("p",null,"For an up to date info about the data received from GitHub, please refer to the ",(0,i.kt)("a",{parentName:"p",href:"https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-the-authenticated-user"},"GitHub API documentation"),".")),(0,i.kt)("h3",{id:"using-the-data-received-from-github"},"Using the Data Received From GitHub"),(0,i.kt)(d.ZP,{mdxType:"OverrideExampleIntro"}),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n gitHub: {\n // highlight-next-line\n configFn: import { getConfig } from "@src/auth/github.js",\n // highlight-next-line\n userSignupFields: import { userSignupFields } from "@src/auth/github.js"\n }\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n')),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},"model User {\n id Int @id @default(autoincrement())\n username String @unique\n displayName String\n}\n\n// ...\n")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-js",metastring:"title=src/auth/github.js",title:"src/auth/github.js"},"export const userSignupFields = {\n username: () => 'hardcoded-username',\n displayName: (data) => data.profile.name,\n}\n\nexport function getConfig() {\n return {\n scopes: ['user'],\n }\n}\n"))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n gitHub: {\n // highlight-next-line\n configFn: import { getConfig } from "@src/auth/github.js",\n // highlight-next-line\n userSignupFields: import { userSignupFields } from "@src/auth/github.js"\n }\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n')),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},"model User {\n id Int @id @default(autoincrement())\n username String @unique\n displayName String\n}\n\n// ...\n")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/auth/github.ts",title:"src/auth/github.ts"},"import { defineUserSignupFields } from 'wasp/server/auth'\n\nexport const userSignupFields = defineUserSignupFields({\n username: () => 'hardcoded-username',\n displayName: (data: any) => data.profile.name,\n})\n\nexport function getConfig() {\n return {\n scopes: ['user'],\n }\n}\n")),(0,i.kt)(h.ZP,{mdxType:"GetUserFieldsType"}))),(0,i.kt)("h2",{id:"using-auth"},"Using Auth"),(0,i.kt)(c.ZP,{mdxType:"UsingAuthNote"}),(0,i.kt)("p",null,"When you receive the ",(0,i.kt)("inlineCode",{parentName:"p"},"user")," object ",(0,i.kt)("a",{parentName:"p",href:"/docs/auth/overview#accessing-the-logged-in-user"},"on the client or the server"),", you'll be able to access the user's GitHub ID like this:"),(0,i.kt)(k.ZP,{mdxType:"GithubData"}),(0,i.kt)(b.ZP,{mdxType:"AccessingUserDataNote"}),(0,i.kt)("h2",{id:"api-reference"},"API Reference"),(0,i.kt)(g.ZP,{mdxType:"ApiReferenceIntro"}),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n gitHub: {\n // highlight-next-line\n configFn: import { getConfig } from "@src/auth/github.js",\n // highlight-next-line\n userSignupFields: import { userSignupFields } from "@src/auth/github.js"\n }\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n'))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n gitHub: {\n // highlight-next-line\n configFn: import { getConfig } from "@src/auth/github.js",\n // highlight-next-line\n userSignupFields: import { userSignupFields } from "@src/auth/github.js"\n }\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n')))),(0,i.kt)("p",null,"The ",(0,i.kt)("inlineCode",{parentName:"p"},"gitHub")," dict has the following properties:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("h4",{parentName:"li",id:"configfn-extimport"},(0,i.kt)("inlineCode",{parentName:"h4"},"configFn: ExtImport")),(0,i.kt)("p",{parentName:"li"},"This function should return an object with the scopes for the OAuth provider."),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-js",metastring:"title=src/auth/github.js",title:"src/auth/github.js"},"export function getConfig() {\n return {\n scopes: [],\n }\n}\n"))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/auth/github.ts",title:"src/auth/github.ts"},"export function getConfig() {\n return {\n scopes: [],\n }\n}\n"))))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("h4",{parentName:"li",id:"usersignupfields-extimport"},(0,i.kt)("inlineCode",{parentName:"h4"},"userSignupFields: ExtImport")),(0,i.kt)(f.ZP,{mdxType:"UserSignupFieldsExplainer"}),(0,i.kt)("p",{parentName:"li"},"Read more about the ",(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields")," function ",(0,i.kt)("a",{parentName:"p",href:"../overview#1-defining-extra-fields"},"here"),"."))))}A.isMDXComponent=!0},29240:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/github-e4d12d3e83fdbfbf93ce1fa831645c0e.png"}}]); \ No newline at end of file +"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[61150],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>h});var a=n(67294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(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 o(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var l=a.createContext({}),u=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):o(o({},t),e)),n},p=function(e){var t=u(e.components);return a.createElement(l.Provider,{value:t},e.children)},d="mdxType",c={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,i=e.mdxType,r=e.originalType,l=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),d=u(n),m=i,h=d["".concat(l,".").concat(m)]||d[m]||c[m]||r;return n?a.createElement(h,o(o({ref:t},p),{},{components:n})):a.createElement(h,o({ref:t},p))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=n.length,o=new Array(r);o[0]=m;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[d]="string"==typeof e?e:i,o[1]=s;for(var u=2;u{n.d(t,{Z:()=>o});var a=n(67294),i=n(86010);const r={tabItem:"tabItem_Ymn6"};function o(e){let{children:t,hidden:n,className:o}=e;return a.createElement("div",{role:"tabpanel",className:(0,i.Z)(r.tabItem,o),hidden:n},t)}},74866:(e,t,n)=>{n.d(t,{Z:()=>N});var a=n(87462),i=n(67294),r=n(86010),o=n(12466),s=n(16550),l=n(91980),u=n(67392),p=n(50012);function d(e){return function(e){return i.Children.map(e,(e=>{if(!e||(0,i.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:i}}=e;return{value:t,label:n,attributes:a,default:i}}))}function c(e){const{values:t,children:n}=e;return(0,i.useMemo)((()=>{const e=t??d(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 h(e){let{queryString:t=!1,groupId:n}=e;const a=(0,s.k6)(),r=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)(r),(0,i.useCallback)((e=>{if(!r)return;const t=new URLSearchParams(a.location.search);t.set(r,e),a.replace({...a.location,search:t.toString()})}),[r,a])]}function g(e){const{defaultValue:t,queryString:n=!1,groupId:a}=e,r=c(e),[o,s]=(0,i.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:r}))),[l,u]=h({queryString:n,groupId:a}),[d,g]=function(e){let{groupId:t}=e;const n=function(e){return e?`docusaurus.tab.${e}`:null}(t),[a,r]=(0,p.Nk)(n);return[a,(0,i.useCallback)((e=>{n&&r.set(e)}),[n,r])]}({groupId:a}),f=(()=>{const e=l??d;return m({value:e,tabValues:r})?e:null})();(0,i.useLayoutEffect)((()=>{f&&s(f)}),[f]);return{selectedValue:o,selectValue:(0,i.useCallback)((e=>{if(!m({value:e,tabValues:r}))throw new Error(`Can't select invalid tab value=${e}`);s(e),u(e),g(e)}),[u,g,r]),tabValues:r}}var f=n(72389);const k={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};function b(e){let{className:t,block:n,selectedValue:s,selectValue:l,tabValues:u}=e;const p=[],{blockElementScrollPositionUntilNextRender:d}=(0,o.o5)(),c=e=>{const t=e.currentTarget,n=p.indexOf(t),a=u[n].value;a!==s&&(d(t),l(a))},m=e=>{let t=null;switch(e.key){case"Enter":c(e);break;case"ArrowRight":{const n=p.indexOf(e.currentTarget)+1;t=p[n]??p[0];break}case"ArrowLeft":{const n=p.indexOf(e.currentTarget)-1;t=p[n]??p[p.length-1];break}}t?.focus()};return i.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,r.Z)("tabs",{"tabs--block":n},t)},u.map((e=>{let{value:t,label:n,attributes:o}=e;return i.createElement("li",(0,a.Z)({role:"tab",tabIndex:s===t?0:-1,"aria-selected":s===t,key:t,ref:e=>p.push(e),onKeyDown:m,onClick:c},o,{className:(0,r.Z)("tabs__item",k.tabItem,o?.className,{"tabs__item--active":s===t})}),n??t)})))}function y(e){let{lazy:t,children:n,selectedValue:a}=e;const r=(Array.isArray(n)?n:[n]).filter(Boolean);if(t){const e=r.find((e=>e.props.value===a));return e?(0,i.cloneElement)(e,{className:"margin-top--md"}):null}return i.createElement("div",{className:"margin-top--md"},r.map(((e,t)=>(0,i.cloneElement)(e,{key:t,hidden:e.props.value!==a}))))}function v(e){const t=g(e);return i.createElement("div",{className:(0,r.Z)("tabs-container",k.tabList)},i.createElement(b,(0,a.Z)({},e,t)),i.createElement(y,(0,a.Z)({},e,t)))}function N(e){const t=(0,f.Z)();return i.createElement(v,(0,a.Z)({key:String(t)},e))}},46300:(e,t,n)=>{n.d(t,{Z:()=>r});var a=n(67294),i=n(50012);function r(e){let{path:t}=e;const[n]=(0,i.Nk)("docusaurus.tab.js-ts"),r=t.lastIndexOf("{"),o=t.slice(r+1,t.length-1),[s,l]=o.split(","),u=t.slice(0,r);return a.createElement("code",null,u+("js"===n?s:l))}},46620:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("small",null,(0,i.kt)("p",null,"Read more about accessing the user data in the ",(0,i.kt)("a",{parentName:"p",href:"/docs/auth/entities/#accessing-the-auth-fields"},"Accessing User Data")," section of the docs.")))}s.isMDXComponent=!0},36318:(e,t,n)=>{n.d(t,{ZP:()=>u});var a=n(87462),i=(n(67294),n(3905)),r=(n(46300),n(85162)),o=n(74866);const s={toc:[]},l="wrapper";function u(e){let{components:t,...n}=e;return(0,i.kt)(l,(0,a.Z)({},s,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields")," defines all the extra fields that need to be set on the ",(0,i.kt)("inlineCode",{parentName:"p"},"User")," during the sign-up process. For example, if you have ",(0,i.kt)("inlineCode",{parentName:"p"},"address")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"phone")," fields on your ",(0,i.kt)("inlineCode",{parentName:"p"},"User")," entity, you can set them by defining the ",(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields")," like this:"),(0,i.kt)(o.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(r.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/auth.js"',title:'"src/auth.js"'},"import { defineUserSignupFields } from 'wasp/server/auth'\n\nexport const userSignupFields = defineUserSignupFields({\n address: (data) => {\n if (!data.address) {\n throw new Error('Address is required')\n }\n return data.address\n }\n phone: (data) => data.phone,\n})\n"))),(0,i.kt)(r.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="src/auth.ts"',title:'"src/auth.ts"'},"import { defineUserSignupFields } from 'wasp/server/auth'\n\nexport const userSignupFields = defineUserSignupFields({\n address: (data) => {\n if (!data.address) {\n throw new Error('Address is required')\n }\n return data.address\n }\n phone: (data) => data.phone,\n})\n")))))}u.isMDXComponent=!0},35208:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-ts"},'const githubIdentity = user.identities.github\n\n// GitHub User ID for example "12345678"\ngithubIdentity.id\n')))}s.isMDXComponent=!0},24373:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"Provider-specific behavior comes down to implementing two functions."),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"configFn")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"userSignupFields"))),(0,i.kt)("p",null,"The reference shows how to define both."),(0,i.kt)("p",null,"For behavior common to all providers, check the general ",(0,i.kt)("a",{parentName:"p",href:"/docs/auth/overview#api-reference"},"API Reference"),"."))}s.isMDXComponent=!0},34626:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"When a user ",(0,i.kt)("strong",{parentName:"p"},"signs in for the first time"),", Wasp creates a new user account and links it to the chosen auth provider account for future logins."))}s.isMDXComponent=!0},63785:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"Wasp automatically generates the ",(0,i.kt)("inlineCode",{parentName:"p"},"defineUserSignupFields")," function to help you correctly type your ",(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields")," object."))}s.isMDXComponent=!0},40971:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"When a user logs in using a social login provider, the backend receives some data about the user.\nWasp lets you access this data inside the ",(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields")," getters."),(0,i.kt)("p",null,"For example, the User entity can include a ",(0,i.kt)("inlineCode",{parentName:"p"},"displayName")," field which you can set based on the details received from the provider."),(0,i.kt)("p",null,"Wasp also lets you customize the configuration of the providers' settings using the ",(0,i.kt)("inlineCode",{parentName:"p"},"configFn")," function."),(0,i.kt)("p",null,"Let's use this example to show both fields in action:"))}s.isMDXComponent=!0},10769:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"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."),(0,i.kt)("p",null,"There are two mechanisms used for overriding the default behavior:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"userSignupFields")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"configFn"))),(0,i.kt)("p",null,"Let's explore them in more detail."))}s.isMDXComponent=!0},75801:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"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 ",(0,i.kt)("a",{parentName:"p",href:"../../auth/overview"},"using auth"),"."))}s.isMDXComponent=!0},79780:(e,t,n)=>{n.d(t,{ZP:()=>s});var a=n(87462),i=(n(67294),n(3905));n(46300);const r={toc:[]},o="wrapper";function s(e){let{components:t,...n}=e;return(0,i.kt)(o,(0,a.Z)({},r,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"Here's a skeleton of how our ",(0,i.kt)("inlineCode",{parentName:"p"},"main.wasp")," should look like after we're done:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},"// Configuring the social authentication\napp myApp {\n auth: { ... }\n}\n\n// Defining routes and pages\nroute LoginRoute { ... }\npage LoginPage { ... }\n")))}s.isMDXComponent=!0},20955:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>w,contentTitle:()=>v,default:()=>A,frontMatter:()=>y,metadata:()=>N,toc:()=>x});var a=n(87462),i=(n(67294),n(3905)),r=n(46300),o=n(85162),s=n(74866),l=n(44996),u=n(34626),p=n(10769),d=n(40971),c=n(75801),m=n(79780),h=n(63785),g=n(24373),f=n(36318),k=n(35208),b=n(46620);const y={title:"GitHub"},v=void 0,N={unversionedId:"auth/social-auth/github",id:"version-0.15.0/auth/social-auth/github",title:"GitHub",description:"Wasp supports Github Authentication out of the box.",source:"@site/versioned_docs/version-0.15.0/auth/social-auth/github.md",sourceDirName:"auth/social-auth",slug:"/auth/social-auth/github",permalink:"/docs/auth/social-auth/github",draft:!1,editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/versioned_docs/version-0.15.0/auth/social-auth/github.md",tags:[],version:"0.15.0",frontMatter:{title:"GitHub"},sidebar:"docs",previous:{title:"Overview",permalink:"/docs/auth/social-auth/overview"},next:{title:"Google",permalink:"/docs/auth/social-auth/google"}},w={},x=[{value:"Setting up Github Auth",id:"setting-up-github-auth",level:2},{value:"1. Adding Github Auth to Your Wasp File",id:"1-adding-github-auth-to-your-wasp-file",level:3},{value:"2. Add the User Entity",id:"2-add-the-user-entity",level:3},{value:"3. Creating a GitHub OAuth App",id:"3-creating-a-github-oauth-app",level:3},{value:"4. Adding Environment Variables",id:"4-adding-environment-variables",level:3},{value:"5. Adding the Necessary Routes and Pages",id:"5-adding-the-necessary-routes-and-pages",level:3},{value:"6. Creating the Client Pages",id:"6-creating-the-client-pages",level:3},{value:"Conclusion",id:"conclusion",level:3},{value:"Default Behaviour",id:"default-behaviour",level:2},{value:"Overrides",id:"overrides",level:2},{value:"Data Received From GitHub",id:"data-received-from-github",level:3},{value:"Using the Data Received From GitHub",id:"using-the-data-received-from-github",level:3},{value:"Using Auth",id:"using-auth",level:2},{value:"API Reference",id:"api-reference",level:2}],T={toc:x},C="wrapper";function A(e){let{components:t,...y}=e;return(0,i.kt)(C,(0,a.Z)({},T,y,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"Wasp supports Github Authentication out of the box.\nGitHub is a great external auth choice when you're building apps for developers, as most of them already have a GitHub account."),(0,i.kt)("p",null,"Letting your users log in using their GitHub accounts turns the signup process into a breeze."),(0,i.kt)("p",null,"Let's walk through enabling Github Authentication, explain some of the default settings, and show how to override them."),(0,i.kt)("h2",{id:"setting-up-github-auth"},"Setting up Github Auth"),(0,i.kt)("p",null,"Enabling GitHub Authentication comes down to a series of steps:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Enabling GitHub authentication in the Wasp file."),(0,i.kt)("li",{parentName:"ol"},"Adding the ",(0,i.kt)("inlineCode",{parentName:"li"},"User")," entity."),(0,i.kt)("li",{parentName:"ol"},"Creating a GitHub OAuth app."),(0,i.kt)("li",{parentName:"ol"},"Adding the necessary Routes and Pages"),(0,i.kt)("li",{parentName:"ol"},"Using Auth UI components in our Pages.")),(0,i.kt)(m.ZP,{mdxType:"WaspFileStructureNote"}),(0,i.kt)("h3",{id:"1-adding-github-auth-to-your-wasp-file"},"1. Adding Github Auth to Your Wasp File"),(0,i.kt)("p",null,"Let's start by properly configuring the Auth object:"),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n // highlight-next-line\n // 1. Specify the User entity (we\'ll define it next)\n // highlight-next-line\n userEntity: User,\n methods: {\n // highlight-next-line\n // 2. Enable Github Auth\n // highlight-next-line\n gitHub: {}\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n'))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n // highlight-next-line\n // 1. Specify the User entity (we\'ll define it next)\n // highlight-next-line\n userEntity: User,\n methods: {\n // highlight-next-line\n // 2. Enable Github Auth\n // highlight-next-line\n gitHub: {}\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n')))),(0,i.kt)("h3",{id:"2-add-the-user-entity"},"2. Add the User Entity"),(0,i.kt)("p",null,"Let's now define the ",(0,i.kt)("inlineCode",{parentName:"p"},"app.auth.userEntity")," entity in the ",(0,i.kt)("inlineCode",{parentName:"p"},"schema.prisma")," file:"),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},"// 3. Define the user entity\nmodel User {\n // highlight-next-line\n id Int @id @default(autoincrement())\n // Add your own fields below\n // ...\n}\n"))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},"// 3. Define the user entity\nmodel User {\n // highlight-next-line\n id Int @id @default(autoincrement())\n // Add your own fields below\n // ...\n}\n")))),(0,i.kt)("h3",{id:"3-creating-a-github-oauth-app"},"3. Creating a GitHub OAuth App"),(0,i.kt)("p",null,"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:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Log into your GitHub account and navigate to: ",(0,i.kt)("a",{parentName:"li",href:"https://github.com/settings/developers"},"https://github.com/settings/developers"),"."),(0,i.kt)("li",{parentName:"ol"},"Select ",(0,i.kt)("strong",{parentName:"li"},"New OAuth App"),"."),(0,i.kt)("li",{parentName:"ol"},"Supply required information.")),(0,i.kt)("img",{alt:"GitHub Applications Screenshot",src:(0,l.Z)("img/integrations-github-1.png"),width:"400px"}),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"For ",(0,i.kt)("strong",{parentName:"li"},"Authorization callback URL"),":",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"For development, put: ",(0,i.kt)("inlineCode",{parentName:"li"},"http://localhost:3001/auth/github/callback"),"."),(0,i.kt)("li",{parentName:"ul"},"Once you know on which URL your API server will be deployed, you can create a new app with that URL instead e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"https://your-server-url.com/auth/github/callback"),".")))),(0,i.kt)("ol",{start:4},(0,i.kt)("li",{parentName:"ol"},"Hit ",(0,i.kt)("strong",{parentName:"li"},"Register application"),"."),(0,i.kt)("li",{parentName:"ol"},"Hit ",(0,i.kt)("strong",{parentName:"li"},"Generate a new client secret")," on the next page."),(0,i.kt)("li",{parentName:"ol"},"Copy your Client ID and Client secret as you'll need them in the next step.")),(0,i.kt)("h3",{id:"4-adding-environment-variables"},"4. Adding Environment Variables"),(0,i.kt)("p",null,"Add these environment variables to the ",(0,i.kt)("inlineCode",{parentName:"p"},".env.server")," file at the root of your project (take their values from the previous step):"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash",metastring:'title=".env.server"',title:'".env.server"'},"GITHUB_CLIENT_ID=your-github-client-id\nGITHUB_CLIENT_SECRET=your-github-client-secret\n")),(0,i.kt)("h3",{id:"5-adding-the-necessary-routes-and-pages"},"5. Adding the Necessary Routes and Pages"),(0,i.kt)("p",null,"Let's define the necessary authentication Routes and Pages."),(0,i.kt)("p",null,"Add the following code to your ",(0,i.kt)("inlineCode",{parentName:"p"},"main.wasp")," file:"),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'// ...\n\nroute LoginRoute { path: "/login", to: LoginPage }\npage LoginPage {\n component: import { Login } from "@src/pages/auth.jsx"\n}\n'))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'// ...\n\nroute LoginRoute { path: "/login", to: LoginPage }\npage LoginPage {\n component: import { Login } from "@src/pages/auth.tsx"\n}\n')))),(0,i.kt)("p",null,"We'll define the React components for these pages in the ",(0,i.kt)(r.Z,{path:"src/pages/auth.{jsx,tsx}",mdxType:"FileExtSwitcher"})," file below."),(0,i.kt)("h3",{id:"6-creating-the-client-pages"},"6. Creating the Client Pages"),(0,i.kt)("admonition",{type:"info"},(0,i.kt)("p",{parentName:"admonition"},"We are using ",(0,i.kt)("a",{parentName:"p",href:"https://tailwindcss.com/"},"Tailwind CSS")," to style the pages. Read more about how to add it ",(0,i.kt)("a",{parentName:"p",href:"../../project/css-frameworks"},"here"),".")),(0,i.kt)("p",null,"Let's create a ",(0,i.kt)(r.Z,{path:"auth.{jsx,tsx}",mdxType:"FileExtSwitcher"})," file in the ",(0,i.kt)("inlineCode",{parentName:"p"},"src/pages")," folder and add the following to it:"),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/pages/auth.jsx"',title:'"src/pages/auth.jsx"'},'import { LoginForm } from \'wasp/client/auth\'\n\nexport function Login() {\n return (\n \n \n \n )\n}\n\n// A layout component to center the content\nexport function Layout({ children }) {\n return (\n
\n
\n
\n
{children}
\n
\n
\n
\n )\n}\n'))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="src/pages/auth.tsx"',title:'"src/pages/auth.tsx"'},'import { LoginForm } from \'wasp/client/auth\'\n\nexport function Login() {\n return (\n \n \n \n )\n}\n\n// A layout component to center the content\nexport function Layout({ children }: { children: React.ReactNode }) {\n return (\n
\n
\n
\n
{children}
\n
\n
\n
\n )\n}\n')))),(0,i.kt)("p",null,"We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components ",(0,i.kt)("a",{parentName:"p",href:"../../auth/ui"},"here"),"."),(0,i.kt)("h3",{id:"conclusion"},"Conclusion"),(0,i.kt)("p",null,"Yay, we've successfully set up Github Auth! \ud83c\udf89"),(0,i.kt)("p",null,(0,i.kt)("img",{alt:"Github Auth",src:n(55333).Z,width:"1315",height:"800"})),(0,i.kt)("p",null,"Running ",(0,i.kt)("inlineCode",{parentName:"p"},"wasp db migrate-dev")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"wasp start")," should now give you a working app with authentication.\nTo see how to protect specific pages (i.e., hide them from non-authenticated users), read the docs on ",(0,i.kt)("a",{parentName:"p",href:"../../auth/overview"},"using auth"),"."),(0,i.kt)("h2",{id:"default-behaviour"},"Default Behaviour"),(0,i.kt)("p",null,"Add ",(0,i.kt)("inlineCode",{parentName:"p"},"gitHub: {}")," to the ",(0,i.kt)("inlineCode",{parentName:"p"},"auth.methods")," dictionary to use it with default settings."),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:"title=main.wasp",title:"main.wasp"},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n // highlight-next-line\n gitHub: {}\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n'))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:"title=main.wasp",title:"main.wasp"},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n // highlight-next-line\n gitHub: {}\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n')))),(0,i.kt)(u.ZP,{mdxType:"DefaultBehaviour"}),(0,i.kt)("h2",{id:"overrides"},"Overrides"),(0,i.kt)(p.ZP,{mdxType:"OverrideIntro"}),(0,i.kt)("h3",{id:"data-received-from-github"},"Data Received From GitHub"),(0,i.kt)("p",null,"We are using GitHub's API and its ",(0,i.kt)("inlineCode",{parentName:"p"},"/user")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"/user/emails")," endpoints to get the user data."),(0,i.kt)("admonition",{title:"We combine the data from the two endpoints",type:"info"},(0,i.kt)("p",{parentName:"admonition"},"You'll find the emails in the ",(0,i.kt)("inlineCode",{parentName:"p"},"emails")," property in the object that you receive in ",(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields"),"."),(0,i.kt)("p",{parentName:"admonition"},"This is because we combine the data from the ",(0,i.kt)("inlineCode",{parentName:"p"},"/user")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"/user/emails")," endpoints ",(0,i.kt)("strong",{parentName:"p"},"if the ",(0,i.kt)("inlineCode",{parentName:"strong"},"user")," or ",(0,i.kt)("inlineCode",{parentName:"strong"},"user:email")," scope is requested."))),(0,i.kt)("p",null,"The data we receive from GitHub on the ",(0,i.kt)("inlineCode",{parentName:"p"},"/user")," endpoint looks something this:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-json"},'{\n "login": "octocat",\n "id": 1,\n "name": "monalisa octocat",\n "avatar_url": "https://github.com/images/error/octocat_happy.gif",\n "gravatar_id": ""\n // ...\n}\n')),(0,i.kt)("p",null,"And the data from the ",(0,i.kt)("inlineCode",{parentName:"p"},"/user/emails")," endpoint looks something like this:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-json"},'[\n {\n "email": "octocat@github.com",\n "verified": true,\n "primary": true,\n "visibility": "public"\n }\n]\n')),(0,i.kt)("p",null,"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 ",(0,i.kt)("inlineCode",{parentName:"p"},"user")," or ",(0,i.kt)("inlineCode",{parentName:"p"},"user:email")," scope in the ",(0,i.kt)("inlineCode",{parentName:"p"},"configFn")," function."),(0,i.kt)("small",null,(0,i.kt)("p",null,"For an up to date info about the data received from GitHub, please refer to the ",(0,i.kt)("a",{parentName:"p",href:"https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-the-authenticated-user"},"GitHub API documentation"),".")),(0,i.kt)("h3",{id:"using-the-data-received-from-github"},"Using the Data Received From GitHub"),(0,i.kt)(d.ZP,{mdxType:"OverrideExampleIntro"}),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n gitHub: {\n // highlight-next-line\n configFn: import { getConfig } from "@src/auth/github.js",\n // highlight-next-line\n userSignupFields: import { userSignupFields } from "@src/auth/github.js"\n }\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n')),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},"model User {\n id Int @id @default(autoincrement())\n username String @unique\n displayName String\n}\n\n// ...\n")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-js",metastring:"title=src/auth/github.js",title:"src/auth/github.js"},"export const userSignupFields = {\n username: () => 'hardcoded-username',\n displayName: (data) => data.profile.name,\n}\n\nexport function getConfig() {\n return {\n scopes: ['user'],\n }\n}\n"))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n gitHub: {\n // highlight-next-line\n configFn: import { getConfig } from "@src/auth/github.js",\n // highlight-next-line\n userSignupFields: import { userSignupFields } from "@src/auth/github.js"\n }\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n')),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-prisma",metastring:'title="schema.prisma"',title:'"schema.prisma"'},"model User {\n id Int @id @default(autoincrement())\n username String @unique\n displayName String\n}\n\n// ...\n")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/auth/github.ts",title:"src/auth/github.ts"},"import { defineUserSignupFields } from 'wasp/server/auth'\n\nexport const userSignupFields = defineUserSignupFields({\n username: () => 'hardcoded-username',\n displayName: (data: any) => data.profile.name,\n})\n\nexport function getConfig() {\n return {\n scopes: ['user'],\n }\n}\n")),(0,i.kt)(h.ZP,{mdxType:"GetUserFieldsType"}))),(0,i.kt)("h2",{id:"using-auth"},"Using Auth"),(0,i.kt)(c.ZP,{mdxType:"UsingAuthNote"}),(0,i.kt)("p",null,"When you receive the ",(0,i.kt)("inlineCode",{parentName:"p"},"user")," object ",(0,i.kt)("a",{parentName:"p",href:"/docs/auth/overview#accessing-the-logged-in-user"},"on the client or the server"),", you'll be able to access the user's GitHub ID like this:"),(0,i.kt)(k.ZP,{mdxType:"GithubData"}),(0,i.kt)(b.ZP,{mdxType:"AccessingUserDataNote"}),(0,i.kt)("h2",{id:"api-reference"},"API Reference"),(0,i.kt)(g.ZP,{mdxType:"ApiReferenceIntro"}),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n gitHub: {\n // highlight-next-line\n configFn: import { getConfig } from "@src/auth/github.js",\n // highlight-next-line\n userSignupFields: import { userSignupFields } from "@src/auth/github.js"\n }\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n'))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'app myApp {\n wasp: {\n version: "^0.15.0"\n },\n title: "My App",\n auth: {\n userEntity: User,\n methods: {\n gitHub: {\n // highlight-next-line\n configFn: import { getConfig } from "@src/auth/github.js",\n // highlight-next-line\n userSignupFields: import { userSignupFields } from "@src/auth/github.js"\n }\n },\n onAuthFailedRedirectTo: "/login"\n },\n}\n')))),(0,i.kt)("p",null,"The ",(0,i.kt)("inlineCode",{parentName:"p"},"gitHub")," dict has the following properties:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("h4",{parentName:"li",id:"configfn-extimport"},(0,i.kt)("inlineCode",{parentName:"h4"},"configFn: ExtImport")),(0,i.kt)("p",{parentName:"li"},"This function should return an object with the scopes for the OAuth provider."),(0,i.kt)(s.Z,{groupId:"js-ts",mdxType:"Tabs"},(0,i.kt)(o.Z,{value:"js",label:"JavaScript",mdxType:"TabItem"},(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-js",metastring:"title=src/auth/github.js",title:"src/auth/github.js"},"export function getConfig() {\n return {\n scopes: [],\n }\n}\n"))),(0,i.kt)(o.Z,{value:"ts",label:"TypeScript",mdxType:"TabItem"},(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-ts",metastring:"title=src/auth/github.ts",title:"src/auth/github.ts"},"export function getConfig() {\n return {\n scopes: [],\n }\n}\n"))))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("h4",{parentName:"li",id:"usersignupfields-extimport"},(0,i.kt)("inlineCode",{parentName:"h4"},"userSignupFields: ExtImport")),(0,i.kt)(f.ZP,{mdxType:"UserSignupFieldsExplainer"}),(0,i.kt)("p",{parentName:"li"},"Read more about the ",(0,i.kt)("inlineCode",{parentName:"p"},"userSignupFields")," function ",(0,i.kt)("a",{parentName:"p",href:"../overview#1-defining-extra-fields"},"here"),"."))))}A.isMDXComponent=!0},55333:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/github-e4d12d3e83fdbfbf93ce1fa831645c0e.png"}}]); \ No newline at end of file diff --git a/assets/js/0608e6cc.925a69e5.js b/assets/js/0608e6cc.c66317e7.js similarity index 98% rename from assets/js/0608e6cc.925a69e5.js rename to assets/js/0608e6cc.c66317e7.js index 3a38f0340b..186e1d2b10 100644 --- a/assets/js/0608e6cc.925a69e5.js +++ b/assets/js/0608e6cc.c66317e7.js @@ -1 +1 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[67434],{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(28738).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},28738:(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([[67434],{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(50286).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},50286:(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/0a3b3433.8f99b470.js b/assets/js/0a3b3433.8f99b470.js new file mode 100644 index 0000000000..b9987c29e6 --- /dev/null +++ b/assets/js/0a3b3433.8f99b470.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[77495],{3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>k});var a=n(67294);function r(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 o(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=a.createContext({}),p=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):o(o({},t),e)),n},c=function(e){var t=p(e.components);return a.createElement(l.Provider,{value:t},e.children)},u="mdxType",m={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},d=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,l=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),u=p(n),d=r,k=u["".concat(l,".").concat(d)]||u[d]||m[d]||i;return n?a.createElement(k,o(o({ref:t},c),{},{components:n})):a.createElement(k,o({ref:t},c))}));function k(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,o=new Array(i);o[0]=d;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[u]="string"==typeof e?e:r,o[1]=s;for(var p=2;p{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(","),p=t.slice(0,i);return a.createElement("code",null,p+("js"===n?s:l))}},87587:(e,t,n)=>{n.d(t,{Jp:()=>i,aH:()=>o});var a=n(67294);const r=e=>{let{color:t,children:n}=e;return a.createElement("span",{style:{border:`2px solid ${t}`,display:"inline-block",padding:"0.2em 0.4em",color:t,borderRadius:"0.4em",fontSize:"0.8em",lineHeight:"1",fontWeight:"bold"}},n)};function i(){return a.createElement(r,{color:"#0b62f5"},"internal")}function o(){return a.createElement(r,{color:"#f59e0b"},"required")}},15954:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>p,contentTitle:()=>s,default:()=>d,frontMatter:()=>o,metadata:()=>l,toc:()=>c});var a=n(87462),r=(n(67294),n(3905)),i=(n(46300),n(87587));const o={title:"Type-Safe Links"},s=void 0,l={unversionedId:"advanced/links",id:"version-0.12.0/advanced/links",title:"Type-Safe Links",description:"If you are using Typescript, you can use Wasp's custom Link component to create type-safe links to other pages on your site.",source:"@site/versioned_docs/version-0.12.0/advanced/links.md",sourceDirName:"advanced",slug:"/advanced/links",permalink:"/docs/0.12.0/advanced/links",draft:!1,editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/versioned_docs/version-0.12.0/advanced/links.md",tags:[],version:"0.12.0",frontMatter:{title:"Type-Safe Links"},sidebar:"docs",previous:{title:"Configuring Middleware",permalink:"/docs/0.12.0/advanced/middleware-config"},next:{title:"Wasp Language (.wasp)",permalink:"/docs/0.12.0/general/language"}},p={},c=[{value:"Using the Link Component",id:"using-the-link-component",level:2},{value:"Using Search Query & Hash",id:"using-search-query--hash",level:3},{value:"The routes Object",id:"the-routes-object",level:2},{value:"API Reference",id:"api-reference",level:2},{value:"Link Component",id:"link-component",level:3},{value:"routes Object",id:"routes-object",level:3}],u={toc:c},m="wrapper";function d(e){let{components:t,...n}=e;return(0,r.kt)(m,(0,a.Z)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"If you are using Typescript, you can use Wasp's custom ",(0,r.kt)("inlineCode",{parentName:"p"},"Link")," component to create type-safe links to other pages on your site."),(0,r.kt)("h2",{id:"using-the-link-component"},"Using the ",(0,r.kt)("inlineCode",{parentName:"h2"},"Link")," Component"),(0,r.kt)("p",null,"After you defined a route:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'route TaskRoute { path: "/task/:id", to: TaskPage }\npage TaskPage { ... }\n')),(0,r.kt)("p",null,"You can get the benefits of type-safe links by using the ",(0,r.kt)("inlineCode",{parentName:"p"},"Link")," component from ",(0,r.kt)("inlineCode",{parentName:"p"},"wasp/client/router"),":"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-jsx",metastring:'title="TaskList.tsx"',title:'"TaskList.tsx"'},"import { Link } from 'wasp/client/router'\n\nexport const TaskList = () => {\n // ...\n\n return (\n
\n {tasks.map((task) => (\n \n {/* \ud83d\udc46 All the params must be correctly passed in */}\n {task.description}\n \n ))}\n
\n )\n}\n")),(0,r.kt)("h3",{id:"using-search-query--hash"},"Using Search Query & Hash"),(0,r.kt)("p",null,"You can also pass ",(0,r.kt)("inlineCode",{parentName:"p"},"search")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"hash")," props to the ",(0,r.kt)("inlineCode",{parentName:"p"},"Link")," component:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="TaskList.tsx"',title:'"TaskList.tsx"'},'\n {task.description}\n\n')),(0,r.kt)("p",null,"This will result in a link like this: ",(0,r.kt)("inlineCode",{parentName:"p"},"/task/1?sortBy=date#comments"),". Check out the ",(0,r.kt)("a",{parentName:"p",href:"#link-component"},"API Reference")," for more details."),(0,r.kt)("h2",{id:"the-routes-object"},"The ",(0,r.kt)("inlineCode",{parentName:"h2"},"routes")," Object"),(0,r.kt)("p",null,"You can also get all the pages in your app with the ",(0,r.kt)("inlineCode",{parentName:"p"},"routes")," object:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-jsx",metastring:'title="TaskList.tsx"',title:'"TaskList.tsx"'},"import { routes } from 'wasp/client/router'\n\nconst linkToTask = routes.TaskRoute.build({ params: { id: 1 } })\n")),(0,r.kt)("p",null,"This will result in a link like this: ",(0,r.kt)("inlineCode",{parentName:"p"},"/task/1"),"."),(0,r.kt)("p",null,"You can also pass ",(0,r.kt)("inlineCode",{parentName:"p"},"search")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"hash")," props to the ",(0,r.kt)("inlineCode",{parentName:"p"},"build")," function. Check out the ",(0,r.kt)("a",{parentName:"p",href:"#routes-object"},"API Reference")," for more details."),(0,r.kt)("h2",{id:"api-reference"},"API Reference"),(0,r.kt)("h3",{id:"link-component"},(0,r.kt)("inlineCode",{parentName:"h3"},"Link")," Component"),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"Link")," component accepts the following props:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("inlineCode",{parentName:"p"},"to")," ",(0,r.kt)(i.aH,{mdxType:"Required"})),(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},"A valid Wasp Route path from your ",(0,r.kt)("inlineCode",{parentName:"li"},"main.wasp")," file."))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("inlineCode",{parentName:"p"},"params: { [name: string]: string | number }")," ",(0,r.kt)(i.aH,{mdxType:"Required"})," (if the path contains params)"),(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},"An object with keys and values for each param in the path."),(0,r.kt)("li",{parentName:"ul"},"For example, if the path is ",(0,r.kt)("inlineCode",{parentName:"li"},"/task/:id"),", then the ",(0,r.kt)("inlineCode",{parentName:"li"},"params")," prop must be ",(0,r.kt)("inlineCode",{parentName:"li"},"{ id: 1 }"),". Wasp supports required and optional params."))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("inlineCode",{parentName:"p"},"search: string[][] | Record | string | URLSearchParams")),(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},"Any valid input for ",(0,r.kt)("inlineCode",{parentName:"li"},"URLSearchParams")," constructor."),(0,r.kt)("li",{parentName:"ul"},"For example, the object ",(0,r.kt)("inlineCode",{parentName:"li"},"{ sortBy: 'date' }")," becomes ",(0,r.kt)("inlineCode",{parentName:"li"},"?sortBy=date"),"."))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("inlineCode",{parentName:"p"},"hash: string"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"all other props that the ",(0,r.kt)("inlineCode",{parentName:"p"},"react-router-dom"),"'s ",(0,r.kt)("a",{parentName:"p",href:"https://v5.reactrouter.com/web/api/Link"},"Link")," component accepts"))),(0,r.kt)("h3",{id:"routes-object"},(0,r.kt)("inlineCode",{parentName:"h3"},"routes")," Object"),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"routes")," object contains a function for each route in your app."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="router.tsx"',title:'"router.tsx"'},'export const routes = {\n // RootRoute has a path like "/"\n RootRoute: {\n build: (options?: {\n search?: string[][] | Record | string | URLSearchParams\n hash?: string\n }) => // ...\n },\n\n // DetailRoute has a path like "/task/:id/:something?"\n DetailRoute: {\n build: (\n options: {\n params: { id: ParamValue; something?: ParamValue; },\n search?: string[][] | Record | string | URLSearchParams\n hash?: string\n }\n ) => // ...\n }\n}\n')),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"params")," object is required if the route contains params. The ",(0,r.kt)("inlineCode",{parentName:"p"},"search")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"hash")," parameters are optional."),(0,r.kt)("p",null,"You can use the ",(0,r.kt)("inlineCode",{parentName:"p"},"routes")," object like this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-tsx"},"import { routes } from 'wasp/client/router'\n\nconst linkToRoot = routes.RootRoute.build()\nconst linkToTask = routes.DetailRoute.build({ params: { id: 1 } })\n")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0a3b3433.995f1851.js b/assets/js/0a3b3433.995f1851.js deleted file mode 100644 index 490ca59ee1..0000000000 --- a/assets/js/0a3b3433.995f1851.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[77495],{3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>k});var a=n(67294);function r(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 o(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=a.createContext({}),p=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):o(o({},t),e)),n},c=function(e){var t=p(e.components);return a.createElement(l.Provider,{value:t},e.children)},u="mdxType",m={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},d=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,l=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),u=p(n),d=r,k=u["".concat(l,".").concat(d)]||u[d]||m[d]||i;return n?a.createElement(k,o(o({ref:t},c),{},{components:n})):a.createElement(k,o({ref:t},c))}));function k(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,o=new Array(i);o[0]=d;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[u]="string"==typeof e?e:r,o[1]=s;for(var p=2;p{n.d(t,{Jp:()=>i,aH:()=>o});var a=n(67294);const r=e=>{let{color:t,children:n}=e;return a.createElement("span",{style:{border:`2px solid ${t}`,display:"inline-block",padding:"0.2em 0.4em",color:t,borderRadius:"0.4em",fontSize:"0.8em",lineHeight:"1",fontWeight:"bold"}},n)};function i(){return a.createElement(r,{color:"#0b62f5"},"internal")}function o(){return a.createElement(r,{color:"#f59e0b"},"required")}},15954:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>p,contentTitle:()=>s,default:()=>d,frontMatter:()=>o,metadata:()=>l,toc:()=>c});var a=n(87462),r=(n(67294),n(3905)),i=n(87587);const o={title:"Type-Safe Links"},s=void 0,l={unversionedId:"advanced/links",id:"version-0.12.0/advanced/links",title:"Type-Safe Links",description:"If you are using Typescript, you can use Wasp's custom Link component to create type-safe links to other pages on your site.",source:"@site/versioned_docs/version-0.12.0/advanced/links.md",sourceDirName:"advanced",slug:"/advanced/links",permalink:"/docs/0.12.0/advanced/links",draft:!1,editUrl:"https://github.com/wasp-lang/wasp/edit/release/web/versioned_docs/version-0.12.0/advanced/links.md",tags:[],version:"0.12.0",frontMatter:{title:"Type-Safe Links"},sidebar:"docs",previous:{title:"Configuring Middleware",permalink:"/docs/0.12.0/advanced/middleware-config"},next:{title:"Wasp Language (.wasp)",permalink:"/docs/0.12.0/general/language"}},p={},c=[{value:"Using the Link Component",id:"using-the-link-component",level:2},{value:"Using Search Query & Hash",id:"using-search-query--hash",level:3},{value:"The routes Object",id:"the-routes-object",level:2},{value:"API Reference",id:"api-reference",level:2},{value:"Link Component",id:"link-component",level:3},{value:"routes Object",id:"routes-object",level:3}],u={toc:c},m="wrapper";function d(e){let{components:t,...n}=e;return(0,r.kt)(m,(0,a.Z)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"If you are using Typescript, you can use Wasp's custom ",(0,r.kt)("inlineCode",{parentName:"p"},"Link")," component to create type-safe links to other pages on your site."),(0,r.kt)("h2",{id:"using-the-link-component"},"Using the ",(0,r.kt)("inlineCode",{parentName:"h2"},"Link")," Component"),(0,r.kt)("p",null,"After you defined a route:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-wasp",metastring:'title="main.wasp"',title:'"main.wasp"'},'route TaskRoute { path: "/task/:id", to: TaskPage }\npage TaskPage { ... }\n')),(0,r.kt)("p",null,"You can get the benefits of type-safe links by using the ",(0,r.kt)("inlineCode",{parentName:"p"},"Link")," component from ",(0,r.kt)("inlineCode",{parentName:"p"},"wasp/client/router"),":"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-jsx",metastring:'title="TaskList.tsx"',title:'"TaskList.tsx"'},"import { Link } from 'wasp/client/router'\n\nexport const TaskList = () => {\n // ...\n\n return (\n
\n {tasks.map((task) => (\n \n {/* \ud83d\udc46 All the params must be correctly passed in */}\n {task.description}\n \n ))}\n
\n )\n}\n")),(0,r.kt)("h3",{id:"using-search-query--hash"},"Using Search Query & Hash"),(0,r.kt)("p",null,"You can also pass ",(0,r.kt)("inlineCode",{parentName:"p"},"search")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"hash")," props to the ",(0,r.kt)("inlineCode",{parentName:"p"},"Link")," component:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-tsx",metastring:'title="TaskList.tsx"',title:'"TaskList.tsx"'},'\n {task.description}\n\n')),(0,r.kt)("p",null,"This will result in a link like this: ",(0,r.kt)("inlineCode",{parentName:"p"},"/task/1?sortBy=date#comments"),". Check out the ",(0,r.kt)("a",{parentName:"p",href:"#link-component"},"API Reference")," for more details."),(0,r.kt)("h2",{id:"the-routes-object"},"The ",(0,r.kt)("inlineCode",{parentName:"h2"},"routes")," Object"),(0,r.kt)("p",null,"You can also get all the pages in your app with the ",(0,r.kt)("inlineCode",{parentName:"p"},"routes")," object:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-jsx",metastring:'title="TaskList.tsx"',title:'"TaskList.tsx"'},"import { routes } from 'wasp/client/router'\n\nconst linkToTask = routes.TaskRoute.build({ params: { id: 1 } })\n")),(0,r.kt)("p",null,"This will result in a link like this: ",(0,r.kt)("inlineCode",{parentName:"p"},"/task/1"),"."),(0,r.kt)("p",null,"You can also pass ",(0,r.kt)("inlineCode",{parentName:"p"},"search")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"hash")," props to the ",(0,r.kt)("inlineCode",{parentName:"p"},"build")," function. Check out the ",(0,r.kt)("a",{parentName:"p",href:"#routes-object"},"API Reference")," for more details."),(0,r.kt)("h2",{id:"api-reference"},"API Reference"),(0,r.kt)("h3",{id:"link-component"},(0,r.kt)("inlineCode",{parentName:"h3"},"Link")," Component"),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"Link")," component accepts the following props:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("inlineCode",{parentName:"p"},"to")," ",(0,r.kt)(i.aH,{mdxType:"Required"})),(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},"A valid Wasp Route path from your ",(0,r.kt)("inlineCode",{parentName:"li"},"main.wasp")," file."))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("inlineCode",{parentName:"p"},"params: { [name: string]: string | number }")," ",(0,r.kt)(i.aH,{mdxType:"Required"})," (if the path contains params)"),(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},"An object with keys and values for each param in the path."),(0,r.kt)("li",{parentName:"ul"},"For example, if the path is ",(0,r.kt)("inlineCode",{parentName:"li"},"/task/:id"),", then the ",(0,r.kt)("inlineCode",{parentName:"li"},"params")," prop must be ",(0,r.kt)("inlineCode",{parentName:"li"},"{ id: 1 }"),". Wasp supports required and optional params."))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("inlineCode",{parentName:"p"},"search: string[][] | Record | string | URLSearchParams")),(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},"Any valid input for ",(0,r.kt)("inlineCode",{parentName:"li"},"URLSearchParams")," constructor."),(0,r.kt)("li",{parentName:"ul"},"For example, the object ",(0,r.kt)("inlineCode",{parentName:"li"},"{ sortBy: 'date' }")," becomes ",(0,r.kt)("inlineCode",{parentName:"li"},"?sortBy=date"),"."))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},(0,r.kt)("inlineCode",{parentName:"p"},"hash: string"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"all other props that the ",(0,r.kt)("inlineCode",{parentName:"p"},"react-router-dom"),"'s ",(0,r.kt)("a",{parentName:"p",href:"https://v5.reactrouter.com/web/api/Link"},"Link")," component accepts"))),(0,r.kt)("h3",{id:"routes-object"},(0,r.kt)("inlineCode",{parentName:"h3"},"routes")," Object"),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"routes")," object contains a function for each route in your app."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-ts",metastring:'title="router.tsx"',title:'"router.tsx"'},'export const routes = {\n // RootRoute has a path like "/"\n RootRoute: {\n build: (options?: {\n search?: string[][] | Record | string | URLSearchParams\n hash?: string\n }) => // ...\n },\n\n // DetailRoute has a path like "/task/:id/:something?"\n DetailRoute: {\n build: (\n options: {\n params: { id: ParamValue; something?: ParamValue; },\n search?: string[][] | Record | string | URLSearchParams\n hash?: string\n }\n ) => // ...\n }\n}\n')),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"params")," object is required if the route contains params. The ",(0,r.kt)("inlineCode",{parentName:"p"},"search")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"hash")," parameters are optional."),(0,r.kt)("p",null,"You can use the ",(0,r.kt)("inlineCode",{parentName:"p"},"routes")," object like this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-tsx"},"import { routes } from 'wasp/client/router'\n\nconst linkToRoot = routes.RootRoute.build()\nconst linkToTask = routes.DetailRoute.build({ params: { id: 1 } })\n")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0c3100e0.641f4db5.js b/assets/js/0c3100e0.a81316d7.js similarity index 87% rename from assets/js/0c3100e0.641f4db5.js rename to assets/js/0c3100e0.a81316d7.js index 5345bcc49c..c14f5a481b 100644 --- a/assets/js/0c3100e0.641f4db5.js +++ b/assets/js/0c3100e0.a81316d7.js @@ -1 +1 @@ -"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[35962],{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(65456).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(4582).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},65456:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/prod_dev_fade-e4097e7d9b64c62ca95bfde692e5115d.svg"},4582:(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([[35962],{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(11866).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(95702).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},11866:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/prod_dev_fade-e4097e7d9b64c62ca95bfde692e5115d.svg"},95702:(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.29511168.js b/assets/js/0dc22d83.29511168.js new file mode 100644 index 0000000000..1c2216dd02 --- /dev/null +++ b/assets/js/0dc22d83.29511168.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkweb=self.webpackChunkweb||[]).push([[56055],{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(95263).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(15508).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(1379).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(85277).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 Matija Sosic
5 min read

Wasp Launch Week #7: Modern Times ⚙️

Read more→
By Milica Maksimović
5 min read

Why Your SaaS Emails Aren’t Being Delivered and How to Fix This Issue

Read more →

By Milica Maksimović
6 min read

Built in Days, Acquired for $20K: The NuloApp Story

Read more →

By Milica Maksimović
13 min read

The Faces Behind Open Source Projects: Tim Jones and pg-boss

Read more →

By Sam Jakshtis
18 min read

Wasp: The JavaScript Answer to Django for Web Development

Read more →

By Lucas Lima do Nascimento
15 min read

How to Add Auth with Lucia to Your React/Next.js App - A Step by Step Guide

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 6665d22d2e..0278e8b801 100644 --- a/blog/2019/09/01/hello-wasp.html +++ b/blog/2019/09/01/hello-wasp.html @@ -18,14 +18,14 @@ - - - + + +

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 def79daa7c..c3942b6b14 100644 --- a/blog/2021/02/23/journey-to-ycombinator.html +++ b/blog/2021/02/23/journey-to-ycombinator.html @@ -18,9 +18,9 @@ - - - + + +
@@ -31,7 +31,7 @@ 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 22e279db0d..cc9355591b 100644 --- a/blog/2021/03/02/wasp-alpha.html +++ b/blog/2021/03/02/wasp-alpha.html @@ -18,9 +18,9 @@ - - - + + +
@@ -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 43ce2c3619..aabca49449 100644 --- a/blog/2021/04/29/discord-bot-introduction.html +++ b/blog/2021/04/29/discord-bot-introduction.html @@ -18,9 +18,9 @@ - - - + + +
@@ -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 8d9e3cffba..868ad75aeb 100644 --- a/blog/2021/09/01/haskell-forall-tutorial.html +++ b/blog/2021/09/01/haskell-forall-tutorial.html @@ -18,9 +18,9 @@ - - - + + +
@@ -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 f06b98ef10..9020e56bdc 100644 --- a/blog/2021/11/21/seed-round.html +++ b/blog/2021/11/21/seed-round.html @@ -18,14 +18,14 @@ - - - + + +

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 aed94b16f0..1f50be0ce8 100644 --- a/blog/2021/11/22/fundraising-learnings.html +++ b/blog/2021/11/22/fundraising-learnings.html @@ -18,16 +18,16 @@ - - - + + +

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 31da71609d..484e8758ce 100644 --- a/blog/2021/12/02/waspello.html +++ b/blog/2021/12/02/waspello.html @@ -18,16 +18,16 @@ - - - + + +

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 d0a62e08d4..e2ea177250 100644 --- a/blog/2021/12/21/shayne-intro.html +++ b/blog/2021/12/21/shayne-intro.html @@ -18,14 +18,14 @@ - - - + + +

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 36e8dba1b5..2f7ff8fc5f 100644 --- a/blog/2022/01/27/waspleau.html +++ b/blog/2022/01/27/waspleau.html @@ -18,14 +18,14 @@ - - - + + +

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 415f49f941..bf66d952a6 100644 --- a/blog/2022/05/31/filip-intro.html +++ b/blog/2022/05/31/filip-intro.html @@ -18,9 +18,9 @@ - - - + + +
@@ -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 83a5450348..b501976a0d 100644 --- a/blog/2022/06/01/gitpod-hackathon-guide.html +++ b/blog/2022/06/01/gitpod-hackathon-guide.html @@ -18,14 +18,14 @@ - - - + + +

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 4b567b5efa..561f1007a1 100644 --- a/blog/2022/06/15/jobs-feature-announcement.html +++ b/blog/2022/06/15/jobs-feature-announcement.html @@ -18,14 +18,14 @@ - - - + + +

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 fec5394eb8..1b2241ddec 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 @@ -18,14 +18,14 @@ - - - + + +

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 df9d1555af..72e1f04ee6 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 @@ -18,14 +18,14 @@ - - - + + +

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 899d28da13..f6c8a236f9 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 @@ -18,14 +18,14 @@ - - - + + +

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 fee79636da..4ef7a7f057 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 @@ -18,14 +18,14 @@ - - - + + +

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 23f7cebedf..c740d4d098 100644 --- a/blog/2022/09/05/dev-excuses-app-tutrial.html +++ b/blog/2022/09/05/dev-excuses-app-tutrial.html @@ -18,14 +18,14 @@ - - - + + +

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 557ab63eff..996bf8654e 100644 --- a/blog/2022/09/29/journey-to-1000-gh-stars.html +++ b/blog/2022/09/29/journey-to-1000-gh-stars.html @@ -18,14 +18,14 @@ - - - + + +

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 51c4a69919..548d6522f6 100644 --- a/blog/2022/10/28/farnance-hackathon-winner.html +++ b/blog/2022/10/28/farnance-hackathon-winner.html @@ -18,14 +18,14 @@ - - - + + +

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 4ff5b12396..02dde80837 100644 --- a/blog/2022/11/15/auth-feature-announcement.html +++ b/blog/2022/11/15/auth-feature-announcement.html @@ -18,14 +18,14 @@ - - - + + +

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 6011735763..6d8cb1ae58 100644 --- a/blog/2022/11/16/alpha-testing-program-post-mortem.html +++ b/blog/2022/11/16/alpha-testing-program-post-mortem.html @@ -18,14 +18,14 @@ - - - + + +

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 128944150f..e6ff67b616 100644 --- a/blog/2022/11/16/tailwind-feature-announcement.html +++ b/blog/2022/11/16/tailwind-feature-announcement.html @@ -18,14 +18,14 @@ - - - + + +

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 1aeace9237..14d8af8e71 100644 --- a/blog/2022/11/17/hacktoberfest-wrap-up.html +++ b/blog/2022/11/17/hacktoberfest-wrap-up.html @@ -18,16 +18,16 @@ - - - + + +

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 cfe01fa5be..564ddcc676 100644 --- a/blog/2022/11/26/erlis-amicus-usecase.html +++ b/blog/2022/11/26/erlis-amicus-usecase.html @@ -18,14 +18,14 @@ - - - + + +

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 238d52a092..da0147c250 100644 --- a/blog/2022/11/26/michael-curry-usecase.html +++ b/blog/2022/11/26/michael-curry-usecase.html @@ -18,14 +18,14 @@ - - - + + +

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 628ed02be6..04d4365e9f 100644 --- a/blog/2022/11/26/wasp-beta-launch-week.html +++ b/blog/2022/11/26/wasp-beta-launch-week.html @@ -18,14 +18,14 @@ - - - + + +

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 29bfb90445..43c789860f 100644 --- a/blog/2022/11/28/why-we-chose-prisma.html +++ b/blog/2022/11/28/why-we-chose-prisma.html @@ -18,14 +18,14 @@ - - - + + +

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 36064c5c64..aa1a111772 100644 --- a/blog/2022/11/29/permissions-in-web-apps.html +++ b/blog/2022/11/29/permissions-in-web-apps.html @@ -18,9 +18,9 @@ - - - + + +
@@ -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 029cb5b13c..7efbf150b4 100644 --- a/blog/2022/11/29/typescript-feature-announcement.html +++ b/blog/2022/11/29/typescript-feature-announcement.html @@ -18,9 +18,9 @@ - - - + + +
@@ -28,7 +28,7 @@ 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 d26e2c0267..abe55190ee 100644 --- a/blog/2022/11/29/wasp-beta.html +++ b/blog/2022/11/29/wasp-beta.html @@ -18,15 +18,15 @@ - - - + + +

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 69309e0915..9baafe855a 100644 --- a/blog/2022/11/30/optimistic-update-feature-announcement.html +++ b/blog/2022/11/30/optimistic-update-feature-announcement.html @@ -18,9 +18,9 @@ - - - + + +
@@ -28,7 +28,7 @@ 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 f5ce2e12d7..eee0430d23 100644 --- a/blog/2022/12/01/beta-ide-improvements.html +++ b/blog/2022/12/01/beta-ide-improvements.html @@ -18,14 +18,14 @@ - - - + + +

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 20de6f82d9..4766b5631b 100644 --- a/blog/2022/12/08/fast-fullstack-chatgpt.html +++ b/blog/2022/12/08/fast-fullstack-chatgpt.html @@ -18,14 +18,14 @@ - - - + + +

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 5856ff9c17..a8bd5f5bd0 100644 --- a/blog/2023/01/11/betathon-review.html +++ b/blog/2023/01/11/betathon-review.html @@ -18,14 +18,14 @@ - - - + + +

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 9ff6a57d57..2b2d5be6e5 100644 --- a/blog/2023/01/18/wasp-beta-update-dec.html +++ b/blog/2023/01/18/wasp-beta-update-dec.html @@ -18,15 +18,15 @@ - - - + + +

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 728445ef02..9c31c27b62 100644 --- a/blog/2023/01/31/wasp-beta-launch-review.html +++ b/blog/2023/01/31/wasp-beta-launch-review.html @@ -18,14 +18,14 @@ - - - + + +

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 c7e6ed155c..30600f2e62 100644 --- a/blog/2023/02/02/no-best-framework.html +++ b/blog/2023/02/02/no-best-framework.html @@ -18,14 +18,14 @@ - - - + + +

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 18e61e155b..bde8cb41b4 100644 --- a/blog/2023/02/14/amicus-indiehacker-interview.html +++ b/blog/2023/02/14/amicus-indiehacker-interview.html @@ -18,15 +18,15 @@ - - - + + +

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 a51806bb30..b8edb33e79 100644 --- a/blog/2023/02/21/junior-developer-misconceptions.html +++ b/blog/2023/02/21/junior-developer-misconceptions.html @@ -18,16 +18,16 @@ - - - + + +

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 2ccde6b2d5..f84c242ee0 100644 --- a/blog/2023/03/02/wasp-beta-update-feb.html +++ b/blog/2023/03/02/wasp-beta-update-feb.html @@ -18,15 +18,15 @@ - - - + + +

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 863f79ef8a..152337ecfe 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 @@ -18,14 +18,14 @@ - - - + + +

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 333ba62683..71e370d6ed 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 @@ -18,14 +18,14 @@ - - - + + +

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 12eade6ea2..455ce10b01 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 @@ -18,14 +18,14 @@ - - - + + +

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 cea50618d0..313657e721 100644 --- a/blog/2023/04/11/wasp-launch-week-two.html +++ b/blog/2023/04/11/wasp-launch-week-two.html @@ -18,14 +18,14 @@ - - - + + +

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 068d4b9f00..3c19d24ef5 100644 --- a/blog/2023/04/12/auth-ui.html +++ b/blog/2023/04/12/auth-ui.html @@ -18,14 +18,14 @@ - - - + + +

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 c66dcc5cfc..0fa71b2ba5 100644 --- a/blog/2023/04/13/db-start-and-seed.html +++ b/blog/2023/04/13/db-start-and-seed.html @@ -18,14 +18,14 @@ - - - + + +

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 5cfa369d63..4cf7646f82 100644 --- a/blog/2023/04/17/How-I-Built-CoverLetterGPT.html +++ b/blog/2023/04/17/How-I-Built-CoverLetterGPT.html @@ -18,14 +18,14 @@ - - - + + +

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 ee4861cf1d..890f9c5132 100644 --- a/blog/2023/04/27/wasp-hackathon-two.html +++ b/blog/2023/04/27/wasp-hackathon-two.html @@ -18,14 +18,14 @@ - - - + + +

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 ee0e3b8133..462edab0b5 100644 --- a/blog/2023/05/19/hackathon-2-review.html +++ b/blog/2023/05/19/hackathon-2-review.html @@ -18,14 +18,14 @@ - - - + + +

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 dc652b8a5e..1eff0c43d4 100644 --- a/blog/2023/06/07/wasp-beta-update-may-23.html +++ b/blog/2023/06/07/wasp-beta-update-may-23.html @@ -18,15 +18,15 @@ - - - + + +

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 5c0086bc1e..9ed4c529a8 100644 --- a/blog/2023/06/22/wasp-launch-week-three.html +++ b/blog/2023/06/22/wasp-launch-week-three.html @@ -18,14 +18,14 @@ - - - + + +

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 a96483fd83..d78153aa8c 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 @@ -18,14 +18,14 @@ - - - + + +

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 f0237c4e41..6d3fc32a1a 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 @@ -18,14 +18,14 @@ - - - + + +

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 b02a7a04a8..fec7a778bf 100644 --- a/blog/2023/06/29/new-wasp-lsp.html +++ b/blog/2023/06/29/new-wasp-lsp.html @@ -18,14 +18,14 @@ - - - + + +

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 3e6b690211..3f57e1a6e9 100644 --- a/blog/2023/06/30/tutorial-jam.html +++ b/blog/2023/06/30/tutorial-jam.html @@ -18,16 +18,16 @@ - - - + + +

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:

  • Use Wasp.
  • Be written in English.
  • Be original content and not copied from any existing sources.
  • Be a written tutorial posted to a social blogging platform like dev.to or hashnode.dev, or a YouTube video tutorial
  • Contain the hashtag #buildwithwasp
  • Submitted by pasting the link in the #tutorialjam channel on our Discord Server AND
  • The tutorial can focus on any topic and be any length (short or long) just as long as it uses Wasp’s fullstack capabilities.

https://media1.giphy.com/media/iB4PoTVka0Xnul7UaC/giphy.gif?cid=7941fdc67jeepog7whrdmkbux0c6kxzb8eyhqwpjcd1tunvp&ep=v1_gifs_search&rid=giphy.gif&ct=g

Judging Criteria​

The judging criteria for the Tutorial Jam will be based on:

  • Clarity and conciseness of the tutorial.
  • Creativity and originality of the tutorial.
  • Effectiveness of the tutorial in helping the reader understand and use Wasp to create a fullstack web app or demonstrate a web development topic.

Templates & Tutorial Examples​

We have a whole repo of starter templates that you can use with Wasp by installing wasp and running wasp new in the command line. The interactive prompt will ask you what template you’d like to start with:

[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 Google auth, ChatGPT API, Tailwind, & Stripe payments.
[4] embeddings
    Comes with code for generating vector embeddings and performing vector similarity search.
[5] WaspAI
    An AI powered code scaffolder. Tell it what kind of app you want and get a scaffolded fullstack app

In addition, here are some ideas to help you get inspired. You could build a simple fullstack app with Wasp in order to explain some key concepts:

  • Wasp’s New AI-Generated App Feature: build any fullstack app using Wasp’s new AI-generated App feature and explain the process.
    • What worked? What didn’t? What are some prompt engineering tips? What did you have to do to get the app in a desired final state?
  • Full-Stack Type Safety: Using Wasp’s low-on-boilerplate fullstack typesaftey, you could dive deep into types on both frontend and backend.
    • How does Wasp’s fullstack typesafety compare to tRPC and/or the T3 stack?
  • Data Management: With complete control and easy implementation of data models, you could explore the concepts of databases, data management and relational data in a simplified environment.
    • What are some tips and tricks for working with Prisma and relational DBs?
  • Understanding Fullstack Web Development: Wasp being a fullstack tool truly shines a light on how front-end and back-end connect in web development. It’s a great tool for understanding how queries, actions, and other operations in back-end can be utilized in front-end components.
    • How does the HTTP protocol work in detail?

Or you could write a tutorial that explains how to build:

  • A vector-powered AI app: Leverage Wasp’s truly fullstack, serverful architecture to build a personalised tool powered by embeddings and vector stores.
  • Realtime Chat or Polling App: Any realtime app could take advantage of Wasp’s easy-to-use websockets features. The tutorial could explain handling real-time data, and other basic back-end concepts.
  • Online Shop: An e-commerce platform model with features like user registration, product display, a shopping cart, and a check-out process, using Wasp’s easy to configure authorization, and database management.

Prizes​

The winners of the Wasp Tutorial Jam will receive the following prizes:

  • First Place: Wasp-colored mechanical keyboard, and your tutorial and info featured on all our blogs (Wasp official website, dev.to, and hashnode)
  • Second Place: 3 months access to PluralSight courses (tons of Software Development courses, tutorials and lessons!) or a $75 Amazon giftcard, and your tutorial featured on all our blogs
  • Third Place: Wasp Swag and a feature of your tutorial and info on our social media channels.

Submission Deadline​

All submissions must be received by Sunday, July 16th 11:59 p.m. CET. Winners will be announced the following week.

Questions?​

Head on over to our Discord Server and ask away :)

Good luck!

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/07/10/gpt-web-app-generator.html b/blog/2023/07/10/gpt-web-app-generator.html index e5c560cb78..f7dbd17450 100644 --- a/blog/2023/07/10/gpt-web-app-generator.html +++ b/blog/2023/07/10/gpt-web-app-generator.html @@ -18,15 +18,15 @@ - - - + + +

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

· 6 min read
Martin Sosic

This project started out as an experiment - we were interested if, given a short description, GPT can generate a full-stack web app in React & Node.js. The results went beyond our expectations!

How it works​

All you have to do in order to use GPT Web App Generator is provide a short description of your app idea in plain English. You can optionally select your app's brand color and the preferred authentication method (more methods coming soon).

1. Describe your app 2. Pick the color 3. Generate your app 🚀

That's it - in a matter of minutes, a full-stack web app codebase, written in React, Node.js, Prisma, and Wasp, will be generated right in front of you, and available for you to download, run it locally and deploy with a single CLI command!

See a full one-minute demo here:


Check out this blog post if you are interested in technical details of how implemented the Generator!

The stack 📚​

Besides React & Node.js, GPT Web App Generator uses Prisma and Wasp.

Prisma is a type-safe database ORM built on top of PostgreSQL. It makes it easy to deal with data models and database migrations.

Wasp is a batteries-included, full-stack framework for React & Node.js. It takes care of everything from front-end to back-end and database along with authentication, sending emails, async jobs, deployment, and more.

Additionaly, all the code behind GPT Web App Generator is completely open-source: web app, GPT code agent.

What kind of apps can I build with it?​

caution

Since this is a GPT-powered project, it's output is not 100% deterministic and small mistakes will sometimes occur in the generated code. For the typical examples of web apps (as seen below) they are usually very minor and straightforward to fix. If you get stuck, ping us on our Discord.

The generated apps are full-stack and consist of front-end, back-end and database. Here are few of the examples we successfully created:

My Plants - track your plants' watering schedule 🌱🚰​

  • See the generated code and run it yourself here

This app does exactly what it says - makes sure that you water your plants on time! It comes with a fully functioning front-end, back-end and the database with User and Plant entities. It also features a full-stack authentication (username & password) and a Tailwind-based design.

The next step would be to add more advanced features, such as email reminders (via Wasp email sending support) when it is time to water your plant.

You can see and download the entire source code and add more features and deploy the app yourself!

ToDo app - a classic ✅​

  • See the generated code and run it yourself here

What kind of a demo would this be if it didn't include a ToDo app? GPT Web App Generator successfully scaffolded it, along with all the basic functionality - creating and marking a task as done.

With the foundations in place (full-stack code, authentication, Tailwind CSS design) you can see & download the code here and try it yourself!

Limitations​

In order to reduce the complexity and therefore mistakes GPT makes, for this first version of Generator we went with the following limitations regarding generated apps:

  1. No additional npm dependencies.
  2. No additional files beyond Wasp Pages (React) and Operations (Node). So no additional files with React components, CSS, utility JS, images or similar.
  3. No TypeScript, just Javascript.
  4. No advanced Wasp features (e.g. Jobs, Auto CRUD, Websockets, Social Auth, email sending, …).

Summary & next steps​

As mentioned above, our goal was to test whether GPT can be effectively used to generate full-stack web applications with React & Node.js. While it's now obvious it can, we have lot of ideas for new features and improvements.

Challenges​

While we were expecting the main issue to be the size of context that GPT has, it turned out to be that the bigger issue is its “smarts”, which determine things like its planning capabilities, capacity to follow provided instructions (we had quite some laughs observing how it sometimes ignores our instructions), and capacity to not do silly mistakes. We saw GPT4 give better results than GPT3.5, but both still make mistakes, and GPT4 is also quite slow/expensive. Therefore we are quite excited about the further developments in the field of AI / LLMs, as they will directly affect the quality of the output for the tools like our Generator.

Next features wishlist​

  1. Get feedback on this initial experiment - both on the Generator and the Wasp as a framework itself: best place to leave us feedback is on our Discord.
  2. Further improve code agent & web app.
  3. Release new version of wasp CLI that allows generating new Wasp project by providing short description via CLI. Our code agent will then use GPT to generate project on the disk. This is already ready and should be coming out soon.
  4. Also allow Wasp users to use code agent for scaffolding specific parts of their Wasp app → you want to add a new Wasp Page (React)? Run our code agent via Wasp CLI or via Wasp vscode extension and have it generated for you, with initial logic already implemented.
  5. As LLMs progress, try some alternative approaches, e.g. try fine-tuning an LLM with knowledge about Wasp, or give LLM more freedom while generating files and parts of the codebase.
  6. Write a detailed blog post about how we implemented the Generator, which techniques we used, how we designed our prompts, what worked and what didn’t work, … .

Support us! ⭐️​

If you wish to express your support for what we are doing, consider giving us a star on Github! Everything we do at Wasp is open source, and your support motivates us and helps us to keep making web app development easier and with less boilerplate.

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/07/17/how-we-built-gpt-web-app-generator.html b/blog/2023/07/17/how-we-built-gpt-web-app-generator.html index 524bae02b5..6fe17f2c70 100644 --- a/blog/2023/07/17/how-we-built-gpt-web-app-generator.html +++ b/blog/2023/07/17/how-we-built-gpt-web-app-generator.html @@ -18,16 +18,16 @@ - - - + + +

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

· 23 min read
Martin Sosic

We created GPT Web App Generator, which lets you shortly describe the web app you would like to create, and in a matter of minutes, a full-stack codebase, written in React, Node.js, Prisma, and Wasp, will be generated right in front of you, and available to download and run locally!

We started this as an experiment, to see how well we could use GPT to generate full-stack web apps in Wasp, the open-source JS web app framework that we are developing. Since we launched, we had more than 3000 apps generated in just a couple of days!

1. Describe your app 2. Pick the color 3. Generate your app 🚀

Check out this blog post to see GPT Web App Generator in action, including a one-minute demo video, few example apps, and learn a bit more about our plans for the future. Or, try it out yourself at https://magic-app-generator.wasp-lang.dev/ !

In this blog post, we are going to explore the technical side of creating the GPT Web App Generator: techniques we used, how we engineered our prompts, challenges we encountered, and choices we made! (Note from here on we will just refer to it as the “Generator”, or “code agent” when talking about the backend)

Also, all the code behind the Generator is open source: web app, GPT code agent.

How well does it work 🤔?​

First, let’s quickly explain what we ended up with and how it performs.

Input into our Generator is the app name, app description (free form text), and a couple of simple options such as primary app color, temperature, auth method, and GPT model to use.

Input for generating a Todo app

As an output, Generator spits out the whole JS codebase of a working full-stack web app: frontend, backend, and database. Frontend is React + Tailwind, the backend is NodeJS with Express, and for working with the database we used Prisma. This is all connected together with the Wasp framework.

You can see an example of generated codebase here: https://magic-app-generator.wasp-lang.dev/result/07ed440a-3155-4969-b3f5-2031fb1f622f .

Result of generating a Todo app

Generator does its best to produce code that works out of the box → you can download it to your machine and run it. For simpler apps, such as TodoApp or MyPlants, it often generates code with no mistakes, and you can run them out of the box.

What generated TodoApp looks like

For a bit more complex apps, like a blog with posts and comments, it still generates a reasonable codebase but there are some mistakes to be expected here and there. For even more complex apps, it usually doesn’t follow up completely, but stops at some level of complexity and fills in the rest with TODOs or omits functionality, so it is kind of like a simplified model of what was asked for. Overall, it is optimized for producing CRUD business web apps.

This makes it a great tool for kick-starting your next web app project with a solid prototype, or to even generate working, simple apps on the fly!

How does it work ⚙️?​

When we set out to build the Generator, we gave ourselves the following goals:

  • we must be able to build it in a couple of weeks
  • it has to be relatively easy to maintain in the future
  • it needs to generate the app quickly and cheaply (a couple of minutes, < $1)
  • generated apps should have as few mistakes as possible

Therefore, to keep it simple, we don’t do any LLM-level engineering or fine-tuning, instead, we just use OpenAI API (specifically GPT3.5 and GPT4) to generate different parts of the app while giving it the right context at every moment (pieces of docs, examples, guidelines, …). To ensure the coherence and quality of the generated app, we don’t give our code agent too much freedom but instead heavily guide it, step by step, through generating the app.

As step zero, we generate some code files deterministically, without GPT, just based on the options that the user chose (primary color, auth method): those include some config files for the project, some basic global CSS, and some auth logic. You can see this logic here (we call those “skeleton” files): code on Github .

Then, the code agent takes over!

The code agent does its work in 3 main phases:

  1. Planning 📝
  2. Generating 🏭
  3. Fixing 🔧

Since GPT4 is quite slower and significantly more expensive than GPT3.5 (also has a lower rate limit regarding the number of tokens per minute, and also the number of requests per minute), we use GPT4 only for the planning, since that is the crucial step, and then after that, we use GPT3.5 for the rest.

As for cost per app 💸: one app typically consumes from 25k to 60k tokens, which comes to about $0.1 to $0.2 per app, when we use a mix of GPT4 and GPT3.5. If we run it just with GPT4, then the cost is 10x, which is from $1 to $2.

🎶 Intermezzo: short explanation of OpenAI Chat Completions API​

OpenAI API offers different services, but we used only one of them: “chat completions”.

API itself is actually very simple: you send over a conversation, and you get a response from the GPT.

The conversation is just a list of messages, where each message has content and a role, where the role specifies who “said” that content → was it “user” (you), or “assistant” (GPT).

The important thing to note is that there is no concept of state/memory: every API call is completely standalone, and the only thing that GPT knows about is the conversation you provide it with at that moment!

If you are wondering how ChatGPT (the web app that uses GPT in the background) works with no memory → well, each time you write a message, the whole conversation so far is resent again! There are some additional smart mechanisms in play here, but that is really it at its core.

Official guide, official API reference.

Step #1: Planning 📝​

A Wasp app consists of Entities (Prisma data models), Operations (NodeJS Queries and Actions), and Pages (React).

Once given an app description and title, the code agent first generates a Plan: it is a list of Entities, Operations (Queries and Actions), and Pages that comprise the app. So kind of like an initial draft of the app. It doesn’t generate the code yet → instead, it comes up with their names and some other details, including a short description of what they should behave like.

This is done via a single API request toward GPT, where the prompt consists of the following:

  • Short info about the Wasp framework + an example of some Wasp code.
  • We explain that we want to generate the Plan, explain what it is, and how it is represented as JSON, by describing its schema.
  • We provide some examples of the Plan, represented as JSON.
  • Some rules and guidelines we want it to follow (e.g. “plan should have at least 1 page”, “make sure to generate a User entity”).
  • Instructions to return the Plan only as a valid JSON response, and no other text.
  • App name and description (as provided by the user).

You can see how we generate such a prompt in the code here.

Also, here is an actual instance of this prompt for a TodoApp. 
Wasp is a full-stack web app framework that uses React (for client), NodeJS and Prisma (for server).
High-level of the app is described in main.wasp file (which is written in special Wasp DSL), details in JS/JSX files.
Wasp DSL (used in main.wasp) reminds a bit of JSON, and doesn't use single quotes for strings, only double quotes. Examples will follow.

Important Wasp features:
  - Routes and Pages: client side, Pages are written in React.
  - Queries and Actions: RPC, called from client, execute on server (nodejs).
    Queries are for fetching and should not do any mutations, Actions are for mutations.
  - Entities: central data models, defined via PSL (Prisma schema language), manipulated via Prisma.
Typical flow: Routes point to Pages, Pages call Queries and Actions, Queries and Actions work with Entities.

Example main.wasp (comments are explanation for you):

```wasp
app todoApp {
  wasp: { version: "^0.11.1" },
  title: "ToDo App",
  auth: {
    userEntity: User,
    methods: { usernameAndPassword: {} },
    onAuthFailedRedirectTo: "/login"
  },
  client: {
    rootComponent: import { Layout } from "@client/Layout.jsx",
  },
  db: {
    prisma: {
      clientPreviewFeatures: ["extendedWhereUnique"]
    }
  },
}

route SignupRoute { path: "/signup", to: SignupPage }
page SignupPage {
  component: import Signup from "@client/pages/auth/Signup.jsx"
}

route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import Login from "@client/pages/auth/Login.jsx"
}

route DashboardRoute { path: "/", to: Dashboard }
page DashboardPage {
  authRequired: true,
  component: import Dashboard from "@client/pages/Dashboard.jsx"
}

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

entity Task {=psl
    id          Int       @id @default(autoincrement())
    description String
    isDone      Boolean   @default(false)
    user        User      @relation(fields: [userId], references: [id])
    userId      Int
psl=}

query getUser {
  fn: import { getUser } from "@server/queries.js",
  entities: [User] // Entities that this query operates on.
}

query getTasks {
  fn: import { getTasks } from "@server/queries.js",
  entities: [Task]
}

action createTask {
  fn: import { createTask } from "@server/actions.js",
  entities: [Task]
}

action updateTask {
  fn: import { updateTask } from "@server/actions.js",
  entities: [Task]
}
```

We are looking for a plan to build a new Wasp app (description at the end of prompt).

Instructions you must follow while generating plan:
  - App uses username and password authentication.
  - App MUST have a 'User' entity, with following fields required:
  - `id Int @id @default(autoincrement())`
  - `username String @unique`
  - `password String`
It is also likely to have a field that refers to some other entity that user owns, e.g. `tasks Task[]`.
  - One of the pages in the app must have a route path "/".
  - Don't generate the Login or Signup pages and routes under any circumstances. They are already generated.

Plan is represented as JSON with the following schema:

{
  "entities": [{ "entityName": string, "entityBodyPsl": string }],
  "actions": [{ "opName": string, "opFnPath": string, "opDesc": string }],
  "queries": [{ "opName": string, "opFnPath": string, "opDesc": string }],
  "pages": [{ "pageName": string, "componentPath": string, "routeName": string, "routePath": string, "pageDesc": string }]
}

Here is an example of a plan (a bit simplified, as we didn't list all of the entities/actions/queries/pages):

{
  "entities": [{
    "entityName": "User",
    "entityBodyPsl": "  id Int @id @default(autoincrement())\n  username String @unique\n  password String\n  tasks Task[]"
  }],
  "actions": [{
    "opName": "createTask",
    "opFnPath": "@server/actions.js",
    "opDesc": "Checks that user is authenticated and if so, creates new Task belonging to them. Takes description as an argument and by default sets isDone to false. Returns created Task."
  }],
  "queries": [{
    "opName": "getTask",
    "opFnPath": "@server/queries.js",
    "opDesc": "Takes task id as an argument. Checks that user is authenticated, and if so, fetches and returns their task that has specified task id. Throws HttpError(400) if tasks exists but does not belong to them."
  }],
  "pages": [{
    "pageName": "TaskPage",
    "componentPath": "@client/pages/Task.jsx",
    "routeName: "TaskRoute",
    "routePath": "/task/:taskId",
    "pageDesc": "Diplays a Task with the specified taskId. Allows editing of the Task. Uses getTask query and createTask action.",
  }]
}

We will later use this plan to write main.wasp file and all the other parts of Wasp app,
so make sure descriptions are detailed enough to guide implementing them.
Also, mention in the descriptions of actions/queries which entities they work with,
and in descriptions of pages mention which actions/queries they use.

Typically, plan will have AT LEAST one query, at least one action, at least one page, and at
least two entities. It will very likely have more than one of each, though.

DO NOT create actions for login and logout under any circumstances. They are already included in Wasp.

Note that we are using SQLite as a database for Prisma, so don't use scalar arrays in PSL, like `String[]`,
as those are not supported in SQLite. You can of course normally use arrays of other models, like `Task[]`.

Please, respond ONLY with a valid JSON that is a plan.
There should be no other text in the response.

==== APP DESCRIPTION: ====

App name: TodoApp
A simple todo app with one main page that lists all the tasks. User can create new tasks by providing their description, toggle existing ones, or edit their description. User owns tasks. User can only see and edit their own tasks. Tasks are saved in the database.

GPT then responds with a JSON (hopefully), that we parse, and we have ourselves a Plan! We will use this Plan in the following steps, to drive our generation of other parts of the app. Note that GPT sometimes adds text to the JSON response or returns invalid JSON, so we built in some simple approaches to overcome these issues, which we explain in detail later.

🎶 Intermezzo: Common prompt design​

The prompt design we just described above for generating a Plan is actually very similar for other steps (e.g. the Generation and Fixing steps along with their respective sub-steps), so let’s cover those commonalities.

All of the prompts we use more or less adhere to the same basic structure:

  • General context
    • Short info about what Wasp framework is.
    • Doc snippets (with code examples if needed) about whatever we are generating right now (e.g. examples of NodeJS code, or examples of React code).
  • Project context: stuff we generated in the previous steps that is relevant to the current step.
  • Instructions on what we want to generate right now + JSON schema for it + example of such JSON response.
  • Rules and guidelines: this is a good place to warn it about common mistakes it makes, or give it some additional advice, and emphasize what needs to happen and what must not happen.
  • Instructions to respond only with a valid JSON, and no other text.
  • Original user prompt: app name and description (as provided by the user).

We put the original user prompt at the end because then we can tell GPT in the system message after it sees the start of the original user prompt (we have a special header for it), that it needs to treat everything after it as an app description and not as instructions on what to do → this way we attempt to defend from the potential prompt injection.

Step #2: Generating 🏭​

After producing the Plan, Generator goes step by step through the Plan and asks GPT to generate each web app piece, while providing it with docs, examples, and guidelines. Each time a web app piece is generated, Generator fits it into the whole app. This is where most of our work comes in: equipping GPT with the right information at the right moment.

In our case, we do it for all the Operations in the Plan (Actions and Queries: NodeJs code), and also for all the Pages in the Plan (React code), with one prompt for each. So if we have 2 queries, 3 actions, and 2 pages, that will be 2+3+2 = 7 GPT prompts/requests. Prompts are designed as explained previously.

Code on Github: generating an Operation, generating a Page.

When generating Operations, we provide GPT with the info about the previously generated Entities, while when generating Pages, we provide GPT with the info about previously generated Entities and Operations.

Step #3: Fixing 🔧​

Finally, the Generator tries its best to fix any mistakes that GPT might have introduced previously. GPT loves fixing stuff it previously generated → if you first ask it to generate some code, and then just tell it to fix it, it will often improve it!

To enhance this process further, we don’t just ask it to fix previous code, but also provide it with instructions on what to keep an eye out for, like common types of mistakes that we noticed it often does, and also point it to any specific mistakes we were able to detect on our own.

Regarding detecting mistakes to report to GPT, ideally, you would have a full REPL going on → that means running the generated code through an interpreter/compiler, then sending it for repairs, and so on until all is fixed.

In our case, running the whole project through the TypeScript compiler was not feasible for us with the time limits we put on ourselves, but we used some simpler static analysis tools like Wasp’s compiler (for the .wasp file) and prisma format for Prisma model schemas, and sent those to GPT to fix them. We also wrote some simple heuristics of our own that are able to detect some of the common mistakes.

Our code (& prompt) for fixing a Page.

Our code (& prompt) for fixing Operations.

In the prompt, we would usually repeat the same guidelines we provided previously in the Generation step, while also adding a couple of additional pointers to common mistakes, and that usually helps, it fixes stuff it missed before. But, often not everything, instead something will still get through. Some things we just couldn’t get it to fix consistently, for example, Wasp-specific JS imports, no matter how much we emphasized what it needed to do with them, it would just keep messing them up. Even GPT4 wasn’t perfect in this situation. For such situations, when possible, we ended up writing our own heuristics that would fix those mistakes (fixing JS imports).

Things we tried/learned​

Explanations 💬​

We tried telling GPT to explain what it did while fixing mistakes: which mistakes it will fix, and which mistakes it fixed, since we read that that can help, but we didn’t see visible improvement in its performance.

Testing 🧪​

Testing the performance of your code agent is hard.

In our case, it takes a couple of minutes for our code agent to generate a new app, and you need to run tests directly with the OpenAI API. Also, since results are non-deterministic, it can be pretty hard to say if output was affected by the changes you did or not.

Finally, evaluating the output itself can be hard (especially in our case when it is a whole full-stack web app).

Ideally, we would have set up a system where we can run only parts of the whole generation process, and we could automatically run a specific part a number of times for each of different sets of parameters (which would include different prompts, but also parameters like type of model (gpt4 vs gpt3.5), temperature and similar), in order to compare performance for each of those parameter sets.

Evaluation performance would also ideally be automated, e.g. we would count the mistakes during compilation and/or evaluate the quality of app design → but this is also quite hard.

We, unfortunately, didn’t have time to set up such a system, so we were mostly doing testing manually, which is quite subjective and vulnerable to randomness, and is effective only for changes that have quite a big impact, while you can’t really detect those that are minor optimizations.

Context vs smarts 🧠​

When we started working on the Generator, we thought the size of GPT’s context would be the main issue. However, we didn’t have any issues with context at the end → most of what we wanted to specify would fit into 2k to max 4k tokens, while GPT3.5 has context up to 16k!

Instead, we had bigger problems with its “smarts” → meaning that GPT would not follow the rules we very explicitly told it to follow, or would do things we explicitly forbid it from doing. GPT4 proved to be better at following rules than GPT3.5, but even GPT4 would keep doing some mistakes over and over and forgetting about specific rules (even though there was more than enough context). The “fixing” step did help with this: we would repeat the rules there and GPT would pick up more of them, but often still not all of them.

Handling JSON as a response 📋​

As mentioned earlier in this article, in all our interactions with GPT, we always ask it to return the response as JSON, for which we specify the schema and give some examples.

However, GPT still doesn’t always follow that rule, and will sometimes add some text around the JSON, or will make a mistake in formatting JSON.

The way we handled this is with two simple fixes:

  1. Upon receiving JSON, we would remove all the characters from the start until we hit {, and also all chars from the end until we hit }. Simple heuristic, but it works very well for removing redundant text around the JSON in practice since GPT will normally not have any { or } in that text.
  2. If we fail to parse JSON, we send it again for repairs, to GPT. We include the previous prompt and its last answer (that contains invalid JSON) and add instructions to fix it + JSON parse errors we got. We repeat this a couple of times until it gets it right (or until we give up).

In practice, these two methods took care of invalid JSON in 99% of the cases for us.

NOTE: While we were implementing our code agent, OpenAI released new functionality for GPT, “functions”, which is basically a mechanism to have GPT respond with a structured JSON, following the schema of your description. So it would likely make more sense to do this with “functions”, but we already had this working well so we just stuck with it.

Handling interruptions in the service 🚧​

We were calling OpenAI API directly, so we noticed quickly that often it would return 503 - service unavailable - especially during peak hours (e.g. 3 pm CET).

Therefore, it is recommended to have some kind of retry mechanism, ideally with exponential backoff, that makes your code agent redundant to such random interruptions in the service, and also to potential rate limiting. We went with the retry mechanism with exponential backoff and it worked great.

Temperature 🌡️​

Temperature determines how creative GPT is, but the more creative it gets, the less “stable” it is. It hallucinates more and also has a harder time following rules. A temperature is a number from 0 to 2, with a default value of 1.

We experimented with different values and found the following:

  • ≥ 1.5 would every so and so start giving quite silly results with random strings in it.
  • ≥ 1.0, < 1.5 was okish but was introducing a bit too many mistakes.
  • ≥ 0.7, < 1.0 was optimal → creative enough, while still not having many mistakes.
  • ≤ 0.7 seemed to perform similarly to a bit higher values, but with a bit less creativity maybe.

That said, I don’t think we tested values below 0.7 enough, and that is something we could certainly work on more.

We ended up using 0.7 as our default value, except for prompts that do fixing, for those we used a lower value of 0.5 because it seemed like GPT was changing stuff too much while fixing at 0.7 (being too creative). Our logic was: let it be creative when writing the first version of the code, then have it be a bit more conventional while fixing it. Again, we haven’t tested all this enough, so this is certainly something I would like us to explore more.

Future 🔮​

While we ended up being impressed with the performance of what we managed to build in such a short time, we were also left wanting to try so many different ideas on how to improve it further. There are many avenues left to be explored in this ecosystem that is developing so rapidly, that it is hard to reach the point where you feel like you explored all the options and found the optimal solution.

Some of the ideas that would be exciting to try in the future:

  1. We put quite a few limitations regarding the code that our code agent generates, to make sure it works well enough: we don’t allow it to create helper files, to include npm dependencies, no TypeScript, no advanced Wasp features, … . We would love to lift the limitations, therefore allowing the creation of more complex and powerful apps.

  2. Instead of our code agent doing everything in one shot, we could allow the user to interact with it after the first version of the app is generated: to provide additional prompts, for example, to fix something, to add some feature to the app, to do something differently, …. The hardest thing here would be figuring out which context to provide to the GPT at which moment and designing the experience appropriately, but I am certain it is doable, and it would take the Generator to the next level of usability. Another option is to allow intervention in between initial generation steps → for example, after the plan is generated, to allow the user to adjust it by providing additional instructions to the GPT.

  3. Find an open-source LLM that fits the purpose and fine-tune / pre-train it for our purpose. If we could teach it more about Wasp and the technologies we use, so we don’t have to include it in every prompt, we could save quite some context + have the LLM be more focused on the rules and guidelines we are specifying in the prompt. We could also host it ourselves and have more control over the costs and rate limits.

  4. Take a different approach to the code agent: let it be more free. Instead of guiding it so carefully, we could teach it about all the different things it is allowed to ask for (ask for docs, ask for examples, ask to generate a certain piece of the app, ask to see a certain already generated piece of the app, …) and would let it guide itself more freely. It could constantly generate a plan, execute it, update the plan, and so on until it reaches the state of equilibrium. This approach potentially promises more flexibility and would likely be able to generate apps of greater complexity, but it also requires quite more tokens and a powerful LLM to drive it → I believe this approach will become more feasible as LLMs become more capable.

Support us! ⭐️​

If you wish to express your support for what we are doing, consider giving us a star on Github! Everything we do at Wasp is open source, and your support motivates us and helps us to keep making web app development easier and with less boilerplate.

Also, if you have any ideas on how we could improve our code agent, or maybe we can help you somehow -> feel free to join our Discord server and let's chat!

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/08/01/smol-ai-vs-wasp-ai.html b/blog/2023/08/01/smol-ai-vs-wasp-ai.html index 32f41d146a..d8b0d364ab 100644 --- a/blog/2023/08/01/smol-ai-vs-wasp-ai.html +++ b/blog/2023/08/01/smol-ai-vs-wasp-ai.html @@ -18,9 +18,9 @@ - - - + + +
@@ -31,7 +31,7 @@ If you click on a post, you are taken to the "View post" page. It also has a 'New post' button, that only logged in users can see, and that takes you to the "New post" page.
  • "New post" page is accessible only by the logged in users. It has a form for creating a new post (title, content).
  • "Edit post" page is accessible only by the post owner. It has a form for editing the post with the id specified in the url.
  • "View post" page is accessible by anybody and it shows the details of the post with the id specified in the url: its title, author, content and comments. It also has a form for creating a new comment, that is accessible only by the logged in users.
    • note

    💡 For the Smol-Developer prompt, I added the lines: “The app consists of a React client and a NodeJS server. Posts are saved in an sqlite database using Prisma ORM.”

    As this was a suggested prompt on the GPT Web App Generator page, let’s start with the Wasp app result first.

    After downloading the generated codebase and running the app, I ran into an error Failed to resolve import "./ext-src/ViewPost.jsx" from "src/router.jsx". Does the file exist?

    One quick look at the main.wasp file revealed that the Generator gave the wrong path to the ViewPost page, although it did get all the other Page paths correct (highlighted in yellow above).

    Once that path was corrected, a working app popped up at localhost:3000. Nice!

    The video above was my first time trying out the app, and as you can see, most of the functionality is there and working correctly — Authentication and Authorization, and basic CRUD operations. Pretty amazing!

    There were still a couple of errors that prevented the app from being fully functional out-of-the-box, but they were easy to fix:

    1. Blog posts on the homepage did not have a link in order to redirect to the their specific post page — fixable by just wrapping them in <Link to={/post/${post.id}}>
    2. The client was passing the postId as a String instead of an Int to the getPost endpoint — fixable by wrapping the argument in parseInt(postId) to convert strings to integers

    And with those simple fixes we got a fully functioning, full-stack blog app with authentication, database, and simple tailwind css styling! The best part was that all this took about ~5 minutes from start to finish. Sweet :)

    note

    🧑‍💻 The Generator saves all the apps it creates along with a sharable link, so if you want to check out the original generated Blog app code (before fixes) from above, click here: https://magic-app-generator.wasp-lang.dev/result/a3a76887-952b-4774-a773-42209c4bffa8

    The Smol-Developer result was also very impressive, with a solid ExpressJS server and a lot of React client pages, but there were too many complicated errors that prevented me from getting the app started, including but not limited to:

    1. No build tools or configuration files
    2. The server was importing database models that didn’t exist
    3. The server was importing but not utilizing Prisma as the ORM to communicate with the DB
    4. Client had Auth logic, but was not utilizing it to protect pages/routes

    Untitled

    Because there were too many fundamental issues with the app, I went ahead and added some more lines to the bottom of the prompt:

    …

    Scaffold the app to be able to use Vite as the client's build tool. Include a package.json file >with the dependencies and scripts for running the client and server.

    This second attempt produced some of the changes I was looking for, like package.json files and Vite config files to bootstrap the React app, but it still failed to include:

    1. An index.html file
    2. Package.json files with the correct dependencies being imported from within the client and server
    3. A prisma.schema file
    4. A css file (although it did include classNames in the jsx code)

    On the other hand, the server code, albeit much sparser this time, did at least import and use Prisma correctly.

    So I went ahead for a third attempt and modified and added the following lines to the bottom of the prompt:

    …

    Scaffold the app to be able to use Vite as the client's build tool.

    Make sure to include the following:

    1. package.json files for both the server and client. Make sure that these files include the >dependencies being imported in the respective apps.
    2. an index.html file in the client's public folder, so that Vite can build the app.
    3. a prisma.schema file with the models and their fields. Make sure these are the same models >being used app-wide.
    4. a css file with styles that match the classNames used in the app.

    With these additions to the prompt, the third iteration of the app did in fact include them! Well, most of them, but unfortunately not all of them. Now I was getting the css and package.json files, but no vite config file was created this time, even though the instructions for using “Vite as the client’s build tool” produced one previously.

    Besides that, no auth logic was implemented, imports were out place or missing, and an index.jsx file was also nowhere to be found, so I decided to stop there.

    I’m sure I could have iterated on the prompt enough times until I got closer to a working app, but at ~$0.80-$1.20 a generation, I didn’t feel like racking up more of an OpenAI bill.

    note

    💸 Price per generation is another big difference between the Smol AI and Wasp AI. Because more work is being done by Wasp’s compiler and less by GPT, each app costs about ~$0.10-$0.20 to generate (although Wasp covers the cost and allows you to use it for free), whereas to generate complex full-stack apps with Smol-Developer can cost upwards of ~$10.00!

    Plus, there are plenty of YouTubers who’ve created videos about the process of using Smol-Developer and it seems they all come to similar conclusions: you need to create a very detailed and explicit prompt in order to get a working prototype (In fact, in AI Jason’s Smol-AI video above, he mentioned that he got the best results out of the box when prompting Smol-Developer to write everything to one file only — of course this limits you to generating simple apps only that are not so easy to continue from manually).

    Thoughts & Further Considerations​

    At their core, SmolAI and WaspAI function quite similarly, by first prompting the LLM to create a plan for the app’s architecture, and then to execute on that plan, file by file.

    But because Smol-Developer aims to be able to generate a wider range of apps, the expectation is on the Developer (or “Prompt Engineer”) to create a highly detailed, explicit prompt, which is more akin to a Product Requirement Doc that a Product Designer would write. This can take a few iterations to get right and pushes Smol-Developer in the direction of “Natural Language Programming” tool.

    On the other hand, Wasp’s GPT Web App Generator has a lot of prompting and programming going on behind the scenes, abstracted away from the user and hidden within the Generator’s code and Wasp’s compiler. Wasp comes with a lot of knowledge baked in and already has a good idea of what it wants to build, which means the user has less to think about it. This means that we’re more likely to get a working complex prototype from a short, simple prompt, but we have less flexibility in the kinds of apps we’re able to create — we always get a full-stack web app.

    In general, Wasp is like a junior developer specialized in web dev and has a lot of experience with a specific stack, while Smol AI is a junior developer that’s a generalist who is more versatile, but has less specific knowledge and experience with web dev 🙂

    Smol AIWasp AI
    🧑‍💻 Types of AppsVariedFull-stack Web Apps
    🗯 Programming LanguagesAll TypesJavaScript/TypeScript
    📈 Complexity of Generated AppSimple to MediumMedium to Complex
    💰 Price per Generation — via OpenAI’s API$0.80 to $10.00$0.10 to $0.20 
    💳 Payment Methodbring your own API keyfree — paid for by Wasp
    🐛 DebuggingYes, if you’re willing to tinkerBuilt-in, but limited
    🗣 Type of Prompt NeededComplex and detailed, 1 or more pages (e.g. an entire Product Requirement Doc)Simple, 1-3 paragraphs
    😎 Intended UserEngineers, Product Designers wanting to generate a broad range of simple prototypesWeb Devs, Product Designers that want a feature rich full-stack web app prototype

    Other big differences lie within:

    1. Error Correction upon Code Creation
      1. Smol AI initially had a debugging script, but this has temporarily deprecated due to the fact that it expects the entire codebase when debugging, and current 32k and 100k token context windows are only available in private beta for GPT4 and Anthropic at the moment.
      2. Wasp AI has some error correction baked into its process, as the structure of a Wasp app is more defined and the range of errors are more predictable.
    2. Price per app generation via OpenAI’s chat completion endpoints
      1. Smol AI can cost anywhere from ~$0.80 to $10.00 depending on the complexity of the app.
      2. Wasp AI costs ~$0.10 to $0.20 per app, when using the default mix of GPT 4 and GPT 3.5 turbo, but Wasp covers the bill here. If you choose to run it just with GPT4, then the cost is 10x at $1.00 to $2.00 per generation and you have to provide your own API key.
    3. User Interface
      1. Smol Developer works through the command line and has minimal logging and process feedback
      2. Wasp AI currently uses a clean web app UI with more logging and feedback, as well as through the command line without a UI (you have to download the experimental Wasp release to do so at this time).

    Overall, both solutions produce amazing results, allowing solo developers or teams iterate on ideas and generate prototypes faster than before. But they still have a lot of room for improvement.

    For example, what these tools lack the most at the moment is in interactive debugging and incremental generation. It would be great if they could allow the user to generate additional code and fix problems in the codebase on the fly, rather than having to go back, rewrite the prompt, and regenerate an entire new codebase.

    I’m not aware of the Smol AI roadmap, but seeing that it’s received a grant from Vercel’s AI accelerator program, I’m sure we will be seeing development on it continue and the tool improve (let me know in the comments if you do have some insight here).

    On the other hand, as I’m a member of the Wasp team, I can confidently say that Wasp will soon be adding the initial generation process and interactive debugging into Wasp’s command line interface!

    So I definitely think it’s early days and that these tools will continue to progress — and continue to produce more impressive results 🚀

    Which Tool Should You Use?​

    Obviously, there can be no clear winner here as the answer to question of which tool you should use as your next “AI Junior Developer” depends largely on your goals.

    Are you looking for a tool that can generate a broad range of simple apps? And are you interested in learning more about building AI-assisted coding tools and natural language programming and don’t mind tweaking and tinkering for a while? Well then, Smol-Developer is what you’re looking for!

    Do you want to generate a working full-stack React/Node app prototype with all the bells and whistles as quickly and easily as possible? Head straight for Wasp’s GPT Web App Generator!

    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

    In general, as Jason “AI Jason” Zhou said:

    “I’m really excited about [AI-assisted coding tools] because if I want to user-test a certain product idea I can ask it to build a prototype very, very quickly, and test with real users”

    Jason makes a great point here, that these tools don’t really have the capacity to replace Junior Developers entirely in their current capacity (although they will surely improve in the future), but they do improve the speed and ease with which we can try out novel ideas!

    I personally believe that in the near future we will see more domain-specific AI-assisted tools like Wasp’s GPT Web App Generator because of the performance gains they bring to the end user. Code agents that are focused on a niche can produce better results out of the box due to the embedded knowledge. In the future, I think we can expect a lot of agents that are each tailored towards fulfilling a specific task.

    But don’t just take my word for it. Go ahead try out Smol-Developer and the GPT Web App Generator for yourself and let me know what you think in the comments!

    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/08/09/build-real-time-voting-app-websockets-react-typescript.html b/blog/2023/08/09/build-real-time-voting-app-websockets-react-typescript.html index d4ac80a5c6..7bb46f8d9f 100644 --- a/blog/2023/08/09/build-real-time-voting-app-websockets-react-typescript.html +++ b/blog/2023/08/09/build-real-time-voting-app-websockets-react-typescript.html @@ -18,15 +18,15 @@ - - - + + +

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

    · 22 min read
    Vinny

    TL;DR​

    WebSockets allow your app to have “real time” features, where updates are instant because they’re passed on an open, two-way channel. This is a different from CRUD apps, which usually use HTTP requests that must establish a connection, send a request, receive a response, and then close the connection.

    To use WebSockets in your React app, you’ll need a dedicated server, such as an ExpressJS app with NodeJS, in order to maintain a persistent connection.

    Unfortunately, serverless solutions (e.g. NextJS, AWS lambda) don’t natively support WebSockets. Bummer. 😞

    Why not? Well, serverless services turn on and off depending on if a request is coming in. With WebSockets, we need this “always on” connection that only a dedicated server can provide (although you can pay for third-party services as a workaround).

    Luckily, we’re going to talk about two great ways you can implement them:

    1. Advanced: Implementing and configuring it yourself with React, NodeJS, and Socket.IO
    2. Easy: By using Wasp, a full-stack React-NodeJS framework, to configure and integrate Socket.IO into your app for you.

    These methods allow you to build fun stuff, like this instantly updating “voting with friends” app we built here:

    You can try out the live demo app here.
    And if you just want the app code, it's available here on GitHub.

    Why WebSockets?​

    So, imagine you're at a party sending text messages to a friend to tell them what food to bring.

    Now, wouldn’t it be easier if you called your friend on the phone so you could talk constantly, instead of sending sporadic messages? That's pretty much what WebSockets are in the world of web applications.

    For example, traditional HTTP requests (e.g. CRUD/RESTful) are like those text messages — your app has to ask the server every time it wants new information, just like you had to send a text message to your friend every time you thought of food for your party.

    But with WebSockets, once a connection is established, it remains open for constant, two-way communication, so the server can send new information to your app the instant it becomes available, even if the client didn’t ask for it.

    This is perfect for real-time applications like chat apps, game servers, or when you're keeping track of stock prices. For example, apps like Google Docs, Slack, WhatsApp, Uber, Zoom, and Robinhood all use WebSockets to power their real-time communication features.

    https://media3.giphy.com/media/26u4hHj87jMePiO3u/giphy.gif?cid=7941fdc6hxgjnub1rcs80udcj652956fwmm4qhxsmk6ldxg7&ep=v1_gifs_search&rid=giphy.gif&ct=g

    So remember, when your app and server have a lot to talk about, go for WebSockets and let the conversation flow freely!

    How WebSockets Work​

    If you want real-time capabilities in your app, you don’t always need WebSockets. You can implement similar functionality by using resource-heavy processes, such as:

    1. long-polling, e.g. running setInterval to periodically hit the server and check for updates.
    2. one-way “server-sent events”, e.g. keeping a unidirectional server-to-client connection open to receive new updates from the server only.

    1. HTTP handshake, 2. two-way instant communication, 3. close connection

    WebSockets, on the other hand, provide a two-way (aka “full-duplex”) communication channel between the client and server.

    Once established via an HTTP “handshake”, the server and client can freely exchange information instantly before the connection is finally closed by either side.

    Although introducing WebSockets does add complexity due to asynchronous and event-driven components, choosing the right libraries and frameworks can make it easy.

    In the sections below, we will show you two ways to implement WebSockets into a React-NodeJS app:

    1. Configuring it yourself alongside your own standalone Node/ExpressJS server
    2. Letting Wasp, a full-stack framework with superpowers, easily configure it for you

    Adding WebSockets Support in a React-NodeJS App​

    What You Shouldn’t Use: Serverless Architecture​

    But first, here’s a “heads up” for you: despite being a great solution for certain use-cases, serverless solutions are not the right tool for this job.

    That means, popular frameworks and infrastructure, like NextJS and AWS Lambda, do not support WebSockets integration out-of-the-box.

    Instead of running on a dedicated, traditional server, such solutions utilize serverless functions (also known as lambda functions), which are designed to execute and complete a task as soon as a request comes in. It’s as if they “turn on” when the request comes in, and then “turn off” once it’s completed.

    This serverless architecture is not ideal for keeping a WebSocket connection alive because we want a persistent, “always-on” connection.

    That’s why you need a “serverful” architecture if you want to build real-time apps. And although there is a workaround to getting WebSockets on a serverless architecture, like using third-party services, this has a number of drawbacks:

    • Cost: these services exist as subscriptions and can get costly as your app scales
    • Limited Customization: you’re using a pre-built solution, so you have less control
    • Debugging: fixing errors gets more difficult, as your app is not running locally

    Using ExpressJS with Socket.IO — Complex/Customizable Method​

    Okay, let's start with the first, more traditional approach: creating a dedicated server for your client to establish a two-way communication channel with.

    This method is more advanced and involves a bit more complexity, but allows for more fine-tuned customization. If you're looking for a straightforward, easier way to bring WebSockets to your React/NodeJS app, we'll get to that in the section below

    note

    👨‍💻 If you want to code along you can follow the instructions below. Alternatively, if you just want to see the finished React-NodeJS full-stack app, check out the github repo here

    In this exampple, we’ll be using ExpressJS with the Socket.IO library. Although there are others out there, Socket.IO is a great library that makes working with WebSockets in NodeJS easier.

    If you want to code along, first clone the start branch:

    git clone --branch start https://github.com/vincanger/websockets-react.git

    You’ll notice that inside we have two folders:

    • 📁 ws-client for our React app
    • 📁 ws-server for our ExpressJS/NodeJS server

    Let’s cd into the server folder and install the dependencies:

    cd ws-server && npm install

    We also need to install the types for working with typescript:

    npm i --save-dev @types/cors

    Now run the server, using the npm start command in your terminal.

    You should see listening on *:8000 printed to the console!

    At the moment, this is what our index.ts file looks like:

    import cors from 'cors';
    import express from 'express';

    const app = express();
    app.use(cors({ origin: '*' }));
    const server = require('http').createServer(app);

    app.get('/', (req, res) => {
      res.send(`<h1>Hello World</h1>`);
    });

    server.listen(8000, () => {
      console.log('listening on *:8000');
    });

    There’s not much going on here, so let’s install the Socket.IO package and start adding WebSockets to our server!

    First, let’s kill the server with ctrl + c and then run: 

    npm install socket.io

    Let’s go ahead and replace the index.ts file with the following code. I know it’s a lot of code, so I’ve left a bunch of comments that explain what’s going on ;):

    import cors from 'cors';
    import express from 'express';
    import { Server, Socket } from 'socket.io';

    type PollState = {
      question: string;
      options: {
        id: number;
        text: string;
        description: string;
        votes: string[];
      }[];
    };
    interface ClientToServerEvents {
      vote: (optionId: number) => void;
      askForStateUpdate: () => void;
    }
    interface ServerToClientEvents {
      updateState: (state: PollState) => void;
    }
    interface InterServerEvents { }
    interface SocketData {
      user: string;
    }

    const app = express();
    app.use(cors({ origin: 'http://localhost:5173' })); // this is the default port that Vite runs your React app on
    const server = require('http').createServer(app);
    // passing these generic type parameters to the `Server` class
    // ensures data flowing through the server are correctly typed.
    const io = new Server<
      ClientToServerEvents,
      ServerToClientEvents,
      InterServerEvents,
      SocketData
    >(server, {
      cors: {
        origin: 'http://localhost:5173',
        methods: ['GET', 'POST'],
      },
    });

    // this is middleware that Socket.IO uses on initiliazation to add
    // the authenticated user to the socket instance. Note: we are not
    // actually adding real auth as this is beyond the scope of the tutorial
    io.use(addUserToSocketDataIfAuthenticated);

    // the client will pass an auth "token" (in this simple case, just the username)
    // to the server on initialize of the Socket.IO client in our React App
    async function addUserToSocketDataIfAuthenticated(socket: Socket, next: (err?: Error) => void) {
      const user = socket.handshake.auth.token;
      if (user) {
        try {
          socket.data = { ...socket.data, user: user };
        } catch (err) {}
      }
      next();
    }

    // the server determines the PollState object, i.e. what users will vote on
    // this will be sent to the client and displayed on the front-end
    const poll: PollState = {
      question: "What are eating for lunch ✨ Let's order",
      options: [
        {
          id: 1,
          text: 'Party Pizza Place',
          description: 'Best pizza in town',
          votes: [],
        },
        {
          id: 2,
          text: 'Best Burger Joint',
          description: 'Best burger in town',
          votes: [],
        },
        {
          id: 3,
          text: 'Sus Sushi Place',
          description: 'Best sushi in town',
          votes: [],
        },
      ],
    };

    io.on('connection', (socket) => {
      console.log('a user connected', socket.data.user);

        // the client will send an 'askForStateUpdate' request on mount
        // to get the initial state of the poll
      socket.on('askForStateUpdate', () => {
        console.log('client asked For State Update');
        socket.emit('updateState', poll);
      });

      socket.on('vote', (optionId: number) => {
        // If user has already voted, remove their vote.
        poll.options.forEach((option) => {
          option.votes = option.votes.filter((user) => user !== socket.data.user);
        });
        // And then add their vote to the new option.
        const option = poll.options.find((o) => o.id === optionId);
        if (!option) {
          return;
        }
        option.votes.push(socket.data.user);
            // Send the updated PollState back to all clients
        io.emit('updateState', poll);
      });

      socket.on('disconnect', () => {
        console.log('user disconnected');
      });
    });

    server.listen(8000, () => {
      console.log('listening on *:8000');
    });

    Great, start the server again with npm start and let’s add the Socket.IO client to the front-end.

    cd into the ws-client directory and run

    cd ../ws-client && npm install

    Next, start the development server with npm run dev and you should see the hardcoded starter app in your browser:

    You may have noticed that poll does not match the PollState from our server. We need to install the Socket.IO client and set it all up in order start our real-time communication and get the correct poll from the server.

    Go ahead and kill the development server with ctrl + c and run:

    npm install socket.io-client

    Now let’s create a hook that initializes and returns our WebSocket client after it establishes a connection. To do that, create a new file in ./ws-client/src called useSocket.ts:

    import { useState, useEffect } from 'react';
    import socketIOClient, { Socket } from 'socket.io-client';

    export type PollState = {
      question: string;
      options: {
        id: number;
        text: string;
        description: string;
        votes: string[];
      }[];
    };
    interface ServerToClientEvents {
      updateState: (state: PollState) => void;
    }
    interface ClientToServerEvents {
      vote: (optionId: number) => void;
      askForStateUpdate: () => void;
    }

    export function useSocket({endpoint, token } : { endpoint: string, token: string }) {
      // initialize the client using the server endpoint, e.g. localhost:8000
        // and set the auth "token" (in our case we're simply passing the username
        // for simplicity -- you would not do this in production!)
        // also make sure to use the Socket generic types in the reverse order of the server!
        const socket: Socket<ServerToClientEvents, ClientToServerEvents>  = socketIOClient(endpoint,  {
        auth: {
          token: token
        }
      }) 
      const [isConnected, setIsConnected] = useState(false);

      useEffect(() => {
        console.log('useSocket useEffect', endpoint, socket)

        function onConnect() {
          setIsConnected(true)
        }

        function onDisconnect() {
          setIsConnected(false)
        }

        socket.on('connect', onConnect)
        socket.on('disconnect', onDisconnect)

        return () => {
          socket.off('connect', onConnect)
          socket.off('disconnect', onDisconnect)
        }
      }, [token]);

        // we return the socket client instance and the connection state
      return {
        isConnected,
        socket,
      };
    }

    Now let’s go back to our main App.tsx page and replace it with the following code (again I’ve left comments to explain):

    import { useState, useMemo, useEffect } from 'react';
    import { Layout } from './Layout';
    import { Button, Card } from 'flowbite-react';
    import { useSocket } from './useSocket';
    import type { PollState } from './useSocket';

    const App = () => {
        // set the PollState after receiving it from the server
      const [poll, setPoll] = useState<PollState | null>(null);
         
        // since we're not implementing Auth, let's fake it by
        // creating some random user names when the App mounts
      const randomUser = useMemo(() => {
        const randomName = Math.random().toString(36).substring(7);
        return `User-${randomName}`;
      }, []);
        
        // 🔌⚡️ get the connected socket client from our useSocket hook! 
      const { socket, isConnected } = useSocket({ endpoint: `http://localhost:8000`, token: randomUser });

      const totalVotes = useMemo(() => {
        return poll?.options.reduce((acc, option) => acc + option.votes.length, 0) ?? 0;
      }, [poll]);

        // every time we receive an 'updateState' event from the server
        // e.g. when a user makes a new vote, we set the React's state
        // with the results of the new PollState 
      socket.on('updateState', (newState: PollState) => {
        setPoll(newState);
      });

      useEffect(() => {
        socket.emit('askForStateUpdate');
      }, []);

      function handleVote(optionId: number) {
        socket.emit('vote', optionId);
      }

      return (
        <Layout user={randomUser}>
          <div className='w-full max-w-2xl mx-auto p-8'>
            <h1 className='text-2xl font-bold'>{poll?.question ?? 'Loading...'}</h1>
            <h2 className='text-lg italic'>{isConnected ? 'Connected ✅' : 'Disconnected 🛑'}</h2>
            {poll && <p className='leading-relaxed text-gray-500'>Cast your vote for one of the options.</p>}
            {poll && (
              <div className='mt-4 flex flex-col gap-4'>
                {poll.options.map((option) => (
                  <Card key={option.id} className='relative transition-all duration-300 min-h-[130px]'>
                    <div className='z-10'>
                      <div className='mb-2'>
                        <h2 className='text-xl font-semibold'>{option.text}</h2>
                        <p className='text-gray-700'>{option.description}</p>
                      </div>
                      <div className='absolute bottom-5 right-5'>
                        {randomUser && !option.votes.includes(randomUser) ? (
                          <Button onClick={() => handleVote(option.id)}>Vote</Button>
                        ) : (
                          <Button disabled>Voted</Button>
                        )}
                      </div>
                      {option.votes.length > 0 && (
                        <div className='mt-2 flex gap-2 flex-wrap max-w-[75%]'>
                          {option.votes.map((vote) => (
                            <div
                              key={vote}
                              className='py-1 px-3 bg-gray-100 rounded-lg flex items-center justify-center shadow text-sm'
                            >
                              <div className='w-2 h-2 bg-green-500 rounded-full mr-2'></div>
                              <div className='text-gray-700'>{vote}</div>
                            </div>
                          ))}
                        </div>
                      )}
                    </div>
                    <div className='absolute top-5 right-5 p-2 text-sm font-semibold bg-gray-100 rounded-lg z-10'>
                      {option.votes.length} / {totalVotes}
                    </div>
                    <div
                      className='absolute inset-0 bg-gradient-to-r from-yellow-400 to-orange-500 opacity-75 rounded-lg transition-all duration-300'
                      style={{
                        width: `${totalVotes > 0 ? (option.votes.length / totalVotes) * 100 : 0}%`,
                      }}
                    ></div>
                  </Card>
                ))}
              </div>
            )}
          </div>
        </Layout>
      );
    };
    export default App;

    Go ahead now and start the client with npm run dev. Open another terminal window/tab, cd into the ws-server directory and run npm start.

    If we did that correctly, we should be seeing our finished, working, REAL TIME app! 🙂

    It looks and works great if you open it up in two or three browser tabs. Check it out:

    Nice!

    So we’ve got the core functionality here, but as this is just a demo, there are a couple very important pieces missing that make this app unusable in production.

    Mainly, we’re creating a random fake user each time the app mounts. You can check this by refreshing the page and voting again. You’ll see the votes just add up, as we’re creating a new random user each time. We don’t want that!

    We should instead be authenticating and persisting a session for a user that’s registered in our database. But another problem: we don’t even have a database at all in this app!

    You can start to see the how the complexity add ups for even just a simple voting feature

    Luckily, our next solution, Wasp, has integrated Authentication and Database Management. Not to mention, it also takes care of a lot of the WebSockets configuration for us.

    So let’s go ahead and give that a go!

    Implementing WebSockets with Wasp — Easier/Less Config Method​

    Because Wasp is an innovative full-stack framework, it makes building React-NodeJS apps quick and developer-friendly.

    Wasp has lots of time-saving features, including WebSocket support via Socket.IO, Authentication, Database Management, and Full-stack type-safety out-of-the box.

    Wasp can take care of all this heavy lifting for you because of its use of a config file, which you can think of like a set of instructions that the Wasp compiler uses to help glue your app together.

    To see it in action, let's implement WebSocket communication using Wasp by following these steps

    tip

    If you just want to see finished app’s code, you can check out the GitHub repo here

    1. Install Wasp globally by running the following command in your terminal:
    curl -sSL https://get.wasp-lang.dev/installer.sh | sh

    If you want to code along, first clone the start branch of the example app:

    git clone --branch start https://github.com/vincanger/websockets-wasp.git

    You’ll notice that the structure of the Wasp app is split:

    • 🐝 a main.wasp config file exists at the root
    • 📁 src/client is our directory for our React files
    • 📁 src/server is our directory for our ExpressJS/NodeJS functions

    Let’s start out by taking a quick look at our main.wasp file.

    app whereDoWeEat {
      wasp: {
        version: "^0.13.2"
      },
      title: "where-do-we-eat",
      client: {
        rootComponent: import { Layout } from "@src/client/Layout",
      },
      // 🔐 This is how we get Auth in our app. Easy!
      auth: {
        userEntity: User,
        onAuthFailedRedirectTo: "/login",
        methods: {
          usernameAndPassword: {}
        }
      },
    }

    // 👱 this is the data model for our registered users in our database
    entity User {=psl
      id       Int     @id @default(autoincrement())
    psl=}

    // ...

    With this, the Wasp compiler will know what to do and will configure these features for us.

    Let’s tell it we want WebSockets, as well. Add the webSocket definition to the main.wasp file, just between auth and dependencies:

    app whereDoWeEat {
        // ... 
      webSocket: {
        fn: import { webSocketFn } from "@src/server/ws-server",
      },
        // ...
    }

    Now we have to define the webSocketFn. In the ./src/server directory create a new file, ws-server.ts and copy the following code:

    import { getUsername } from 'wasp/auth';
    import { type WebSocketDefinition } from 'wasp/server/webSocket';

    type PollState = {
      question: string;
      options: {
        id: number;
        text: string;
        description: string;
        votes: string[];
      }[];
    };

    interface ServerToClientEvents {
      updateState: (state: PollState) => void;
    }
    interface ClientToServerEvents {
      vote: (optionId: number) => void;
      askForStateUpdate: () => void;
    }
    interface InterServerEvents {}

    export const webSocketFn: WebSocketDefinition<ClientToServerEvents, ServerToClientEvents, InterServerEvents> = (
      io,
      _context
    ) => {
      const poll: PollState = {
        question: "What are eating for lunch ✨ Let's order",
        options: [
          {
            id: 1,
            text: 'Party Pizza Place',
            description: 'Best pizza in town',
            votes: [],
          },
          {
            id: 2,
            text: 'Best Burger Joint',
            description: 'Best burger in town',
            votes: [],
          },
          {
            id: 3,
            text: 'Sus Sushi Place',
            description: 'Best sushi in town',
            votes: [],
          },
        ],
      };
      io.on('connection', (socket) => {
        if (!socket.data.user) {
          console.log('Socket connected without user');
          return;
        }

        const connectionUsername = getUsername(socket.data.user);

        console.log('Socket connected: ', connectionUsername);
        socket.on('askForStateUpdate', () => {
          socket.emit('updateState', poll);
        });

        socket.on('vote', (optionId) => {
          if (!connectionUsername) {
            return;
          }
          // If user has already voted, remove their vote.
          poll.options.forEach((option) => {
            option.votes = option.votes.filter((username) => username !== connectionUsername);
          });
          // And then add their vote to the new option.
          const option = poll.options.find((o) => o.id === optionId);
          if (!option) {
            return;
          }
          option.votes.push(connectionUsername);
          io.emit('updateState', poll);
        });

        socket.on('disconnect', () => {
          console.log('Socket disconnected: ', connectionUsername);
        });
      });
    };

    You may have noticed that there’s a lot less configuration and boilerplate needed here in the Wasp implementation. That’s because the:

    • endpoints,
    • authentication,
    • and Express and Socket.IO middleware

    are all being handled for you by Wasp. Noice!

    Let’s go ahead now and run the app to see what we have at this point.

    First, we need to initialize the database so that our Auth works correctly. This is something we didn’t do in the previous example due to high complexity, but is easy to do with Wasp:

    wasp db migrate-dev

    Once that’s finished, run the app (it my take a while on first run to install all depenedencies):

    wasp start

    You should see a login screen this time. Go ahead and first register a user, then login:

    Once logged in, you’ll see the same hardcoded poll data as in the previous example, because, again, we haven’t set up the Socket.IO client on the frontend. But this time it should be much easier.

    Why? Well, besides less configuration, another nice benefit of working with TypeScript with Wasp, is that you just have to define payload types with matching event names on the server, and those types will get exposed automatically on the client!

    Let’s take a look at how that works now.

    In .src/client/MainPage.tsx, replace the contents with the following code:

    // Wasp provides us with pre-configured hooks and types based on
    // our server code. No need to set it up ourselves!
    import { type ServerToClientPayload, useSocket, useSocketListener } from 'wasp/client/webSocket';
    import { useAuth } from 'wasp/client/auth';
    import { useState, useMemo, useEffect } from 'react';
    import { Button, Card } from 'flowbite-react';
    import { getUsername } from 'wasp/auth';

    const MainPage = () => {
      // Wasp provides a bunch of pre-built hooks for us :)
      const { data: user } = useAuth();
      const [poll, setPoll] = useState<ServerToClientPayload<'updateState'> | null>(null);
      const totalVotes = useMemo(() => {
        return poll?.options.reduce((acc, option) => acc + option.votes.length, 0) ?? 0;
      }, [poll]);

      const { socket } = useSocket();

      const username = user ? getUsername(user) : null;

      useSocketListener('updateState', (newState) => {
        setPoll(newState);
      });

      useEffect(() => {
        socket.emit('askForStateUpdate');
      }, []);

      function handleVote(optionId: number) {
        socket.emit('vote', optionId);
      }

      return (
        <div className='w-full max-w-2xl mx-auto p-8'>
          <h1 className='text-2xl font-bold'>{poll?.question ?? 'Loading...'}</h1>
          {poll && <p className='leading-relaxed text-gray-500'>Cast your vote for one of the options.</p>}
          {poll && (
            <div className='mt-4 flex flex-col gap-4'>
              {poll.options.map((option) => (
                <Card key={option.id} className='relative transition-all duration-300 min-h-[130px]'>
                  <div className='z-10'>
                    <div className='mb-2'>
                      <h2 className='text-xl font-semibold'>{option.text}</h2>
                      <p className='text-gray-700'>{option.description}</p>
                    </div>
                    <div className='absolute bottom-5 right-5'>
                      {username && !option.votes.includes(username) ? (
                        <Button onClick={() => handleVote(option.id)}>Vote</Button>
                      ) : (
                        <Button disabled>Voted</Button>
                      )}
                      {!user}
                    </div>
                    {option.votes.length > 0 && (
                      <div className='mt-2 flex gap-2 flex-wrap max-w-[75%]'>
                        {option.votes.map((username, idx) => {
                          return (
                            <div
                              key={username}
                              className='py-1 px-3 bg-gray-100 rounded-lg flex items-center justify-center shadow text-sm'
                            >
                              <div className='w-2 h-2 bg-green-500 rounded-full mr-2'></div>
                              <div className='text-gray-700'>{username}</div>
                            </div>
                          );
                        })}
                      </div>
                    )}
                  </div>
                  <div className='absolute top-5 right-5 p-2 text-sm font-semibold bg-gray-100 rounded-lg z-10'>
                    {option.votes.length} / {totalVotes}
                  </div>
                  <div
                    className='absolute inset-0 bg-gradient-to-r from-yellow-400 to-orange-500 opacity-75 rounded-lg transition-all duration-300'
                    style={{
                      width: `${totalVotes > 0 ? (option.votes.length / totalVotes) * 100 : 0}%`,
                    }}
                  ></div>
                </Card>
              ))}
            </div>
          )}
        </div>
      );
    };
    export default MainPage;

    In comparison to the previous implementation, Wasp saved us from having to configure the Socket.IO client, as well as building our own hooks.

    Also, hover over the variables in your client-side code, and you’ll see that the types are being automatically inferred for you!

    Here’s just one example, but it should work for them all:

    Now if you open up a new private/incognito tab, register a new user, and login, you’ll see a fully working, real-time voting app. The best part is, in comparison to the previous approach, we can log out and back in, and our voting data persists, which is exactly what we’d expect from a production grade app. 🎩

    Awesome… 😏

    Comparing the Two Approaches​

    Now, just because one approach seems easier, doesn’t always mean it’s always better. Let’s give a quick run-down of the advantages and disadvantages of both the implementations above.

    Without WaspWith Wasp
    😎 Intended UserSenior Developers, web development teamsFull-stack developers, “Indiehackers”, junior devs
    📈 Complexity of CodeMedium-to-HighLow
    🚤 SpeedSlower, more methodicalFaster, more integrated
    🧑‍💻 LibrariesAnySocket.IO
    ⛑ Type safetyImplement on both server and clientImplement once on server, inferred by Wasp on client
    🎮 Amount of controlHigh, as you determine the implementationOpinionated, as Wasp decides the basic implementation
    🐛 Learning CurveComplex: full knowledge of front and backend technologies, including WebSocketsIntermediate: Knowledge of full-stack fundamentals necessary.

    Implementing WebSockets Using React, Express.js (Without Wasp)​

    Advantages:

    1. Control & Flexibility: You can approach the implementation of WebSockets in the way that best suits your project's needs, as well as your choice between a number of different WebSocket libraries, not just Socket.IO.

    Disadvantages:

    1. More Code & Complexity: Without the abstractions provided by a framework like Wasp, you might need to write more code and create your own abstractions to handle common tasks. Not to mention the proper configuration of a NodeJS/ExpressJS server (the one provided in the example is very basic)
    2. Manual Type Safety: If you’re working with TypeScript, you have to be more careful typing your event handlers and payload types coming into and going out from the server, or implement a more type-safe approach yourself.

    Implementing WebSockets with Wasp (uses React, ExpressJS, and Socket.IO under the hood)​

    Advantages:

    1. Fully-Integrated/Less code: Wasp provides useful abstractions such as useSocket and useSocketListener hooks for use in React components (on top of other features like Auth, Async Jobs, Email-sending, DB management, and Deployment), simplifying the client-side code, and allowing for full integration with less configuration.
    2. Type Safety: Wasp facilitates full-stack type safety for WebSocket events and payloads. This reduces the likelihood of runtime errors due to mismatched data types and saves you from writing even more boilerplate.

    Disadvantages:

    1. Learning curve: Developers unfamiliar with Wasp will need to learn the framework to effectively use it.
    2. Less control: While Wasp provides a lot of conveniences, it abstracts away some of the details, giving developers slightly less control over certain aspects of socket management.

    Conclusion​

    In general, how you add WebSockets to your React app depends on the specifics of your project, your comfort level with the available tools, and the trade-offs you're willing to make between ease of use, control, and complexity.

    Don’t forget, if you want to check out the full finished code from our “Lunch Voting” example full-stack app, go here: https://github.com/vincanger/websockets-wasp

    And if you know of a better, cooler, sleeker way of implementing WebSockets into your apps, let us know in the comments below

    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/08/23/using-product-requirement-documents-generate-better-web-apps-with-ai.html b/blog/2023/08/23/using-product-requirement-documents-generate-better-web-apps-with-ai.html index 9572bc8fc7..e9fce22ee6 100644 --- a/blog/2023/08/23/using-product-requirement-documents-generate-better-web-apps-with-ai.html +++ b/blog/2023/08/23/using-product-requirement-documents-generate-better-web-apps-with-ai.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@
  • functionality,
  • and behavior

    • of the product to be developed.

    But supplying the PRD is just half the battle. This is because components of your web app within the frontend and backend need to know about each other.

    And this is where most of these tools fall short, with tools like Smol-Developer creating decent client and server code that work great on their own, but unfortunately don’t work together!

    Given this, it seems like an AI tool that already knows the ins and outs of the whole system, that understands the interconnectedness of various parts of a web app, is our best bet.

    In short, we need a tool that doesn't just 'do its task' but 'understands the project'.

    The Best Tool for the Job: GPT Web App Generator.

    Remember, I’m focusing on generating comprehensive full-stack codebases here, and for that Wasp’s GPT Web App Generator gets the job done surprisingly well.

    How does it do this? Well, the full answer lies in how Wasp as a framework is able to help you build full-stack React/NodeJS web apps.

    It’s beyond the scope of this article to explain it in full detail, but the TL;DR is that Wasp has a compiler that helps build your app based on a config file. The config file is like a set of instructions that its compiler understands and uses to piece together the different parts of the full-stack app for you.

    https://media1.giphy.com/media/heVoZxS2qAGk4Ay5E5/giphy.gif?cid=7941fdc6x2abm5omkgd1d79rz6dt5kzaead3mxu8xt4xuwc2&ep=v1_gifs_search&rid=giphy.gif&ct=g

    This is what makes it easier for the AI to get all the pieces of the app right! Once it writes the fundamental client and server code, along with the main config file, the Wasp compiler takes over and pieces it all together, removing a lot of potential possibilities for errors!

    In the end, you get a React/NodeJS codebase with features like:

    1. full-stack auth
    2. server config and API routes
    3. tailwind CSS config and styles
    4. cron jobs and queues
    5. email sending
    6. deployment

    What’s cool too is that this tool doesn't require you to be highly explicit, because the specifics are baked into the tool itself. In other words, it saves you tons of time and energy without compromising on the quality or coherence of the end product.

    The Hack: Getting GPT to write the PRD for you

    Ok, but if you’re like me, you don’t really know how to write a good PRD. Plus, writing a detailed PRD can be pretty time-consuming. But luckily ChatGPT knows how.

    Thanks, ChatGPT 🙏

    So to get really great results out of Wasp’s GPT Web App Generator, I first ask ChatGPT (using GPT-4) to write a detailed product requirement doc for me, like this:

    Write a Product Requirement Document for the following full-stack app:

    An app where users can track their house plants and their watering schedule.

    And then I’ll slightly modify ChatGPT’s output before I pass it to GPT Web App Generator:

    Product Requirements Document for a House Plants Tracking Application

    1. **Product Title**: GreenLush: Your House Plant Care Companion

    2. **Purpose**: 

    The GreenLush app is designed to help users manage their house plants and keep track of their watering schedules. This app will serve as a reminder tool, a database for plant types, and a platform for users to know more about house plant care. 

    3. **Features and Functionality**:

        3.1. **User Registration & Profile Management**: To allow users to create and manage their account.
        
        3.2. **Plant Database**: A comprehensive directory of house plants, with visuals and information about each type.
        
        3.3. **Plant Profile**: Users can create a profile for each house plant they own, fill in its type, and assign a custom nickname and photo.
        
        3.4. **Watering Schedule**: By selecting or inputting the type of plant, the app will suggest an ideal watering schedule. Users can confirm or customize this schedule and notifications will be sent when it's time to water each specific plant. 

        3.5. **House Plant Care Tips**: A section of the app that provides general care tips and recommendations for house plants.

    4. **Behavior of the Product**:

        4.1. Users will be prompted to sign up when they open the app for the first time. 
      
        4.2. Once registered, users will be able to browse the plant database, create and manage plant profiles, set watering schedules, and read plant care tips. 

        4.3. Notification alerts will be sent according to the set watering schedule.

    Image description

    GPT Web App Generator will start generating a plan for your app, execute that plan file by file, and even do some error-checking and fixing.

    Pretty neat!

    Then, the generated app code can be reviewed before you download it and run it locally. This is nice because sometimes it’s useful to tweak the prompt and a few settings to see if you get better results.

    Best of all, the process is free. You don’t even need to use your own API key!

    Image description

    The picture above is the actual generated, working full-stack app I got out-of-the-box from the example prompt above. All I had to do was initialize the database, register/log in, and BOOM, the app was up and running!

    🤩 BTW, If you want to check out the code that GPT Web App Generator created based on the above PRD, go here: https://magic-app-generator.wasp-lang.dev/result/1f28b518-0cca-4352-84e4-69a4ac04d0fa

    There are more examples of types of apps you can build with this tool, written about here, but it’s probably best to just play around with it yourself and see what you can get!

    Conclusion

    There are several really cool AI-assisted coding tools out there, but for kickstarting a full-stack React/NodeJS app, I’ve found GPT Web App Generator to be the best performing one.

    It consistently generates functional, comprehensive full-stack starter codebases that need little to no error-fixing, depending on the complexity of the app.

    Couple that with the “PRD hack”, and you can save yourself a substantial amount of time by avoiding writing a ton of boilerplate.

    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/09/17/ai-meme-generator-how-to-use-openai-function-call.html b/blog/2023/09/17/ai-meme-generator-how-to-use-openai-function-call.html index cf813c88ea..518595e678 100644 --- a/blog/2023/09/17/ai-meme-generator-how-to-use-openai-function-call.html +++ b/blog/2023/09/17/ai-meme-generator-how-to-use-openai-function-call.html @@ -18,16 +18,16 @@ - - - + + +

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

    · 31 min read
    Vinny

    Table of Contents​

    # TL;DR

    In this two-part tutorial, we’re going to build a full-stack instant Meme Generator app using:

    You check out a deployed version of the app we’re going to build here: The Memerator

    If you just want to see the code for the finished app, check out the Memerator’s GitHub Repo

    # Intro

    Call Me, Maybe​

    With OpenAI’s chat completions API, developers are now able to do some really cool stuff. It basically enables ChatGPT functionality, but in the form of a callable API you can integrate into any app.

    But when working with the API, a lot of devs wanted GPT to give back data in a format, like JSON, that they could use in their app’s functions.

    Unfortunately, if you asked ChatGPT to return the data in a certain format, it wouldn’t always get it right. Which is why OpenAI released function calling.

    As they describe it, function calling allows devs to “… describe functions to GPT, and have the model intelligently choose to output a JSON object containing arguments to call those functions.”

    This is a great way to turn natural language into an API call.

    So what better way to learn how to use GPT’s function calling feature than to use it to call Imgflip.com’s meme creator API!?

    Image description

    ## Let’s Build

    In this two-part tutorial, we’re going to build a full-stack React/NodeJS app with:

    • Authentication
    • Meme generation via OpenAI’s function calling and ImgFlip.com’s API
    • Daily cron job to fetch new meme templates
    • Meme editing and deleting
    • and more!

    Image description

    I already deployed a working version of this app that you can try out here: https://damemerator.netlify.app — so give it a go and let’s get… going.

    In Part 1 of this tutorial, we will get the app set up and generating and displaying memes.

    In Part 2, we will add more functionality, like recurring cron jobs to fetch more meme templates, and the ability to edit and delete memes.

    BTW, two quick tips:

    1. if you need to reference the app’s finished code at any time to help you with this tutorial, you can check out the app’s GitHub Repo here.
    2. if you have any questions, feel free to hop into the Wasp Discord Server and ask us!

    Part 1

    Configuration​

    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.

    Set up your Wasp project​

    First, install Wasp by running this in your terminal:

    curl -sSL <https://get.wasp-lang.dev/installer.sh> | sh

    Next, let’s clone the start branch of the Memerator app that I’ve prepared for you:

    git clone -b start https://github.com/vincanger/memerator.git

    Then navigate into the Memerator directory and open up the project in VS Code:

    cd Memerator && code .

    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 check out the main.wasp file first. You can think of it as the “skeleton”, or instructions, of your app. This file configures most of your full-stack app for you 🤯:

    app Memerator {
      wasp: {
        version: "^0.11.3"
      },
      title: "Memerator",
      client: {
        rootComponent: import { Layout } from "@client/Layout",
      },
      db: {
        system: PostgreSQL,
        prisma: {
          clientPreviewFeatures: ["extendedWhereUnique"]
        }
      },
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {}
        },
        onAuthFailedRedirectTo: "/login",
        onAuthSucceededRedirectTo: "/"
      },
      dependencies: [
        ("openai", "4.2.0"),
        ("axios", "^1.4.0"),
        ("react-icons", "4.10.1"),
      ]
    }

    entity User {=psl
        id       Int    @id @default(autoincrement())
        username String @unique
        password String
        memes    Meme[]
        isAdmin  Boolean @default(false)
        credits  Int     @default(2)
    psl=}

    entity Meme {=psl
        id         String @id @default(uuid())
        url        String 
        text0      String
        text1      String
        topics     String 
        audience   String 
        template   Template @relation(fields: [templateId], references: [id])
        templateId String
        user       User   @relation(fields: [userId], references: [id])
        userId     Int    
        createdAt  DateTime @default(now())
    psl=}

    entity Template {=psl
        id       String @id @unique
        name     String
        url      String
        width    Int
        height   Int
        boxCount Int
        memes    Meme[]
    psl=}

    route HomePageRoute { path: "/", to: HomePage }
    page HomePage {
      component: import { HomePage } from "@client/pages/Home",
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import Login from "@client/pages/auth/Login"
    }
    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import Signup from "@client/pages/auth/Signup"
    }

    As you can see, our main.wasp config file has our:

    • dependencies,
    • authentication method,
    • database type, and
    • database models (”entities”)
    • client-side pages & routes

    You might have also 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.

    Also, make sure you install the Wasp VS code extension so that you get nice syntax highlighting and the best overall dev experience.

    Setting up the Database​

    We still need to get a Postgres database setup.

    Usually this can be pretty annoying, but with Wasp it’s really easy.

    1. just have Docker Deskop installed and running,
    2. open up a separate terminal tab/window,
    3. cd into the Memerator directory, 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.

    Now, in a different terminal tab, run

    wasp db migrate-dev

    and make sure to give your database migration a name, like init.

    Environment Variables​

    In the root of your project, you’ll find a .env.server.example file that looks like this:

    # set up your own credentials on https://imgflip.com/signup and rename this file to .env.server
    # NOTE: make sure you register with Username and Password (not google) 
    IMGFLIP_USERNAME=
    IMGFLIP_PASSWORD=

    # get your api key from https://platform.openai.com/
    OPENAI_API_KEY=

    JWT_SECRET=asecretphraseatleastthirtytwocharacterslong

    Rename this file to .env.server and follow the instructions in it to get your:

    as we will need them to generate our memes 🤡

    Start your App​

    With everything setup correctly, you should now be able to run 

    wasp start

    When running wasp start, Wasp will install all the necessary npm packages, start our NodeJS server on port 3001, and our React client on port 3000.

    Head to localhost:3000 in your browser to check it out. We should have the basis for our app that looks like this:

    Image description

    Generating a Meme​

    The boilerplate code already has the client-side form set up for generating memes based on:

    • topics
    • intended audience

    This is the info we will send to the backend to call the OpenAI API using function calls. We then send this info to the imglfip.com API to generate the meme.

    But the /caption_image endpoint of the imgflip API needs the meme template id. And to get that ID we first need to fetch the available meme templates from imgflip’s /get_memes endpoint

    So let’s set that up now.

    Server-Side Code​

    Create a new file in src/server/ called utils.ts:

    import axios from 'axios';
    import { stringify } from 'querystring';
    import HttpError from '@wasp/core/HttpError.js';

    type GenerateMemeArgs = {
      text0: string;
      text1: string;
      templateId: string;
    };

    export const fetchMemeTemplates = async () => {
      try {
        const response = await axios.get('https://api.imgflip.com/get_memes');
        return response.data.data.memes;
      } catch (error) {
        console.error(error);
        throw new HttpError(500, 'Error fetching meme templates');
      }
    };

    export const generateMemeImage = async (args: GenerateMemeArgs) => {
      console.log('args: ', args);

      try {
        const data = stringify({
          template_id: args.templateId,
          username: process.env.IMGFLIP_USERNAME,
          password: process.env.IMGFLIP_PASSWORD,
          text0: args.text0,
          text1: args.text1,
        });

        // Implement the generation of meme using the Imgflip API
        const res = await axios.post('https://api.imgflip.com/caption_image', data, {
          headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
          },
        });

        const url = res.data.data.url;

        console.log('generated meme url: ', url);

        return url as string;
      } catch (error) {
        console.error(error);
        throw new HttpError(500, 'Error generating meme image');
      }
    };

    This gives us some utility functions to help us fetch all the meme templates that we can possibly generate meme images with.

    Notice that the POST request to the /caption_image endpoint takes the following data:

    • our imgflip username and password
    • ID of the meme template we will use
    • the text for top of the meme, i.e. text0
    • the text for the bottom of the meme, i.e. text1

    Image description

    The text0 and text1 arguments will generated for us by our lovely friend, ChatGPT. But in order for GPT to do that, we have to set up its API call, too.

    To do that, create a new file in src/server/ called actions.ts.

    Then go back to your main.wasp config file and add the following Wasp Action at the bottom of the file:

    //...

    action createMeme {
      fn: import { createMeme } from "@server/actions.js",
      entities: [Meme, Template, User]
    }

    An Action is a type of Wasp Operation that changes some state on the backend. It’s essentially a NodeJS function that gets called on the server, but Wasp takes care of setting it all up for you.

    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, you just write the business logic!

    Image description

    If you’ve got the Wasp VS Code extension installed, you’ll see an error (above). Hover over it and click Quick Fix > create function createMeme.

    This will scaffold a createMeme function (below) for you in your actions.ts file if the file exists. Pretty Cool!

    import { CreateMeme } from '@wasp/actions/types'

    type CreateMemeInput = void
    type CreateMemeOutput = void

    export const createMeme: CreateMeme<CreateMemeInput, CreateMemeOutput> = async (args, context) => {
      // Implementation goes here
    }

    You can see that it imports the Action types for you as well.

    Because we will be sending the topics array and the intended audience string for the meme from our front-end form, and in the end we will return the newly created Meme entity, that’s what we should define our types as.

    Remember, the Meme entity is the database model we defined in our main.wasp config file.

    Knowing that, we can change the content of actions.ts to this:

    import type { CreateMeme } from '@wasp/actions/types'
    import type { Meme } from '@wasp/entities';

    type CreateMemeArgs = { topics: string[]; audience: string };

    export const createMeme: CreateMeme<CreateMemeArgs, Meme> = async ({ topics, audience }, context) => {
      // Implementation goes here
    }

    Before we implement the rest of the logic, let’s run through how our createMeme function should work and how our Meme will get generated:

    1. fetch the imgflip meme template we want to use
    2. send its name, the topics, and intended audience to OpenAI’s chat completions API
    3. tell OpenAI we want the result back as arguments we can pass to our next function in JSON format, i.e. OpenAI’s function calling
    4. pass those arguments to the imgflip /caption-image endpoint and get our created meme’s url
    5. save the meme url and other info into our DB as a Meme entity

    With all that in mind, go ahead and entirely replace the content in our actions.ts with the completed createMeme action:

    import HttpError from '@wasp/core/HttpError.js';
    import OpenAI from 'openai';
    import { fetchMemeTemplates, generateMemeImage } from './utils.js';

    import type { CreateMeme } from '@wasp/actions/types';
    import type { Meme, Template } from '@wasp/entities';

    type CreateMemeArgs = { topics: string[]; audience: string };

    const openai = new OpenAI({
      apiKey: process.env.OPENAI_API_KEY,
    });

    export const createMeme: CreateMeme<CreateMemeArgs, Meme> = async ({ topics, audience }, context) => {
      if (!context.user) {
        throw new HttpError(401, 'You must be logged in');
      }

      if (context.user.credits === 0 && !context.user.isAdmin) {
        throw new HttpError(403, 'You have no credits left');
      }

      const topicsStr = topics.join(', ');

      let templates: Template[] = await context.entities.Template.findMany({});

        if (templates.length === 0) {
        const memeTemplates = await fetchMemeTemplates();
        templates = await Promise.all(
          memeTemplates.map(async (template: any) => {
            const addedTemplate = await context.entities.Template.upsert({
              where: { id: template.id },
              create: {
                id: template.id,
                name: template.name,
                url: template.url,
                width: template.width,
                height: template.height,
                boxCount: template.box_count
              },
              update: {}
            });

            return addedTemplate;
          })
        );
      }

      // filter out templates with box_count > 2
      templates = templates.filter((template) => template.boxCount <= 2);
      const randomTemplate = templates[Math.floor(Math.random() * templates.length)];

      console.log('random template: ', randomTemplate);

      const sysPrompt = `You are a meme idea generator. You will use the imgflip api to generate a meme based on an idea you suggest. Given a random template name and topics, generate a meme idea for the intended audience. Only use the template provided`;
      const userPrompt = `Topics: ${topicsStr} \n Intended Audience: ${audience} \n Template: ${randomTemplate.name} \n`;

      let openAIResponse: OpenAI.Chat.Completions.ChatCompletion;
      try {
        openAIResponse = await openai.chat.completions.create({
          messages: [
            { role: 'system', content: sysPrompt },
            { role: 'user', content: userPrompt },
          ],
          functions: [
            {
              name: 'generateMemeImage',
              description: 'Generate meme via the imgflip API based on the given idea',
              parameters: {
                type: 'object',
                properties: {
                  text0: { type: 'string', description: 'The text for the top caption of the meme' },
                  text1: { type: 'string', description: 'The text for the bottom caption of the meme' },
                },
                required: ['templateName', 'text0', 'text1'],
              },
            },
          ],
          function_call: {
            name: 'generateMemeImage',
          },
          model: 'gpt-4-0613',
        });
      } catch (error: any) {
        console.error('Error calling openAI: ', error);
        throw new HttpError(500, 'Error calling openAI');
      }

      console.log(openAIResponse.choices[0]);

      /**
       * the Function call returned by openAI looks like this:
       */
      // {
      //   index: 0,
      //   message: {
      //     role: 'assistant',
      //     content: null,
      //     function_call: {
      //       name: 'generateMeme',
      //       arguments: '{\n' +
      //         `  "text0": "CSS you've been writing all day",\n` +
      //         '  "text1": "This looks horrible"\n' +
      //         '}'
      //     }
      //   },
      //   finish_reason: 'stop'
      // }
      if (!openAIResponse.choices[0].message.function_call) throw new HttpError(500, 'No function call in openAI response');

      const gptArgs = JSON.parse(openAIResponse.choices[0].message.function_call.arguments);
      console.log('gptArgs: ', gptArgs);

      const memeIdeaText0 = gptArgs.text0;
      const memeIdeaText1 = gptArgs.text1;

      console.log('meme Idea args: ', memeIdeaText0, memeIdeaText1);

      const memeUrl = await generateMemeImage({
        templateId: randomTemplate.id,
        text0: memeIdeaText0,
        text1: memeIdeaText1,
      });

      const newMeme = await context.entities.Meme.create({
        data: {
          text0: memeIdeaText0,
          text1: memeIdeaText1,
          topics: topicsStr,
          audience: audience,
          url: memeUrl,
          template: { connect: { id: randomTemplate.id } },
          user: { connect: { id: context.user.id } },
        },
      });

      return newMeme;
    };

    At this point, the code above should be pretty self-explanatory, but I want to highlight a couple points:

    1. the context object is passed through to all Actions and Queries by Wasp. It contains the Prisma client with access to the DB entities you defined in your main.wasp config file.
    2. We first look for the imgflip meme templates in our DB. If none are found, we fetch them using our fetchTemplates utility function we defined earlier. Then we upsert them into our DB.
    3. There are some meme templates that take more than 2 text boxes, but for this tutorial we’re only using meme templates with 2 text inputs to make it easier.
    4. We choose a random template from this list to use as a basis for our meme (it’s actually a great way to serendipitously generate some interesting meme content).
    5. We give the OpenAI API info about the functions it can create arguments for via the functions and function_call properties, which tell it to always return JSON arguments for our function, generateMemeImage

    Great! But once we start generating memes, we will need a way to display them on our front end.

    So let’s now create a Wasp Query. A Query works just like an Action, except it’s only for reading data.

    Go to src/server and create a new file called queries.ts.

    Next, in your main.wasp file add the following code:

    //...

    query getAllMemes {
      fn: import { getAllMemes } from "@server/queries.js",
      entities: [Meme]
    }

    Then in your queries.ts file, add the getAllMemes function:

    import HttpError from '@wasp/core/HttpError.js';

    import type { Meme } from '@wasp/entities';
    import type { GetAllMemes } from '@wasp/queries/types';

    export const getAllMemes: GetAllMemes<void, Meme[]> = async (_args, context) => {
      const memeIdeas = await context.entities.Meme.findMany({
        orderBy: { createdAt: 'desc' },
        include: { template: true },
      });

      return memeIdeas;
    };

    Client-Side Code​

    Now that we’ve got the createMeme and getAllMemes code implemented server-side, let’s hook it up to our client.

    Wasp makes it really easy to import the Operations we just created and call them on our front end.

    You can do so by going to src/client/pages/Home.tsx and adding the following code to the top of the file:

    //...other imports...
    import { useQuery } from '@wasp/queries';
    import createMeme from '@wasp/actions/createMeme';
    import getAllMemes from '@wasp/queries/getAllMemes';
    import useAuth from '@wasp/auth/useAuth';

    export function HomePage() {
      const [topics, setTopics] = useState(['']);
      const [audience, setAudience] = useState('');
      const [isMemeGenerating, setIsMemeGenerating] = useState(false);

      // 😎 😎 😎
      const { data: user } = useAuth();
      const { data: memes, isLoading, error } = useQuery(getAllMemes); 

      const handleGenerateMeme: FormEventHandler<HTMLFormElement> = async (e) => {
        e.preventDefault();
        if (!user) {
          history.push('/login');
          return;
        }
        if (topics.join('').trim().length === 0 || audience.length === 0) {
          alert('Please provide topic and audience');
          return;
        }
        try {
          setIsMemeGenerating(true);
          await createMeme({ topics, audience }); // <--- 😎 😎 😎
        } catch (error: any) {
          alert('Error generating meme: ' + error.message);
        } finally {
          setIsMemeGenerating(false);
        }
      };

    //...

    As you can see, we’ve imported createMeme and getAllMemes (😎).

    For getAllMemes, we wrap it in the useQuery hook so that we can fetch and cache the data. On the other hand, our createMeme Action gets called in handleGenerateMeme which we will call when submit our form.

    Rather than adding code to the Home.tsx file piece-by-piece, here is the file with all the code to generate and display the memes. Go ahead and replace all of Home.tsx with this code and I’ll explain it in more detail below:

    import { useState, FormEventHandler } from 'react';
    import { useQuery } from '@wasp/queries';
    import createMeme from '@wasp/actions/createMeme';
    import getAllMemes from '@wasp/queries/getAllMemes';
    import useAuth from '@wasp/auth/useAuth';
    import { useHistory } from 'react-router-dom';
    import {
      AiOutlinePlusCircle,
      AiOutlineMinusCircle,
      AiOutlineRobot,
    } from 'react-icons/ai';

    export function HomePage() {
      const [topics, setTopics] = useState(['']);
      const [audience, setAudience] = useState('');
      const [isMemeGenerating, setIsMemeGenerating] = useState(false);

      const history = useHistory();
      const { data: user } = useAuth();
      const { data: memes, isLoading, error } = useQuery(getAllMemes);

      const handleGenerateMeme: FormEventHandler<HTMLFormElement> = async (e) => {
        e.preventDefault();
        if (!user) {
          history.push('/login');
          return;
        }
        if (topics.join('').trim().length === 0 || audience.length === 0) {
          alert('Please provide topic and audience');
          return;
        }
        try {
          setIsMemeGenerating(true);
          await createMeme({ topics, audience });
        } catch (error: any) {
          alert('Error generating meme: ' + error.message);
        } finally {
          setIsMemeGenerating(false);
        }
      };

      const handleDeleteMeme = async (id: string) => {
        //...
      };

      if (isLoading) return 'Loading...';
      if (error) return 'Error: ' + error;

      return (
        <div className='p-4'>
          <h1 className='text-3xl font-bold mb-4'>Welcome to Memerator!</h1>
          <p className='mb-4'>Start generating meme ideas by providing topics and intended audience.</p>
          <form onSubmit={handleGenerateMeme}>
            <div className='mb-4 max-w-[500px]'>
              <label htmlFor='topics' className='block font-bold mb-2'>
                Topics:
              </label>
              {topics.map((topic, index) => (
                <input
                  key={index}
                  type='text'
                  id='topics'
                  value={topic}
                  onChange={(e) => {
                    const updatedTopics = [...topics];
                    updatedTopics[index] = e.target.value;
                    setTopics(updatedTopics);
                  }}
                  className='p-1 mr-1 mb-1 border rounded text-lg focus:outline-none focus:ring-2 focus:ring-primary-600 focus:border-transparent'
                />
              ))}
              <div className='flex items-center my-2 gap-1'>
                <button
                  type='button'
                  onClick={() => topics.length < 3 && setTopics([...topics, ''])}
                  className='flex items-center gap-1 bg-primary-200 hover:bg-primary-300 border-2 text-black text-xs py-1 px-2 rounded'
                >
                  <AiOutlinePlusCircle /> Add Topic
                </button>
                {topics.length > 1 && (
                  <button
                    onClick={() => setTopics(topics.slice(0, -1))}
                    className='flex items-center gap-1 bg-red-500 hover:bg-red-700 border-2 text-white text-xs py-1 px-2 rounded'
                  >
                    <AiOutlineMinusCircle /> Remove Topic
                  </button>
                )}
              </div>
            </div>
            <div className='mb-4'>
              <label htmlFor='audience' className='block font-bold mb-2'>
                Intended Audience:
              </label>
              <input
                type='text'
                id='audience'
                value={audience}
                onChange={(e) => setAudience(e.target.value)}
                className='p-1 border rounded text-lg focus:outline-none focus:ring-2 focus:ring-primary-600 focus:border-transparent'
              />
            </div>
            <button
              type='submit'
              className={`flex items-center gap-1 bg-primary-200 hover:bg-primary-300 border-2 text-black text-sm font-bold py-1 px-2 rounded ${
                isMemeGenerating ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer'
              } $}`}
            >
              <AiOutlineRobot />
              {!isMemeGenerating ? 'Generate Meme' : 'Generating...'}
            </button>
          </form>

          {!!memes && memes.length > 0 ? (
            memes.map((memeIdea) => (
              <div key={memeIdea.id} className='mt-4 p-4 bg-gray-100 rounded-lg'>
                <img src={memeIdea.url} width='500px' />
                <div className='flex flex-col items-start mt-2'>
                  <div>
                    <span className='text-sm text-gray-700'>Topics: </span>
                    <span className='text-sm italic text-gray-500'>{memeIdea.topics}</span>
                  </div>
                  <div>
                    <span className='text-sm text-gray-700'>Audience: </span>
                    <span className='text-sm italic text-gray-500'>{memeIdea.audience}</span>
                  </div>
                </div>
                {/* TODO: implement edit and delete meme features */}
              </div>
            ))
          ) : (
            <div className='flex justify-center mt-5'> :( no memes found</div>
          )}
        </div>
      );
    }

    There are two things I want to point out about this code:

    1. The useQuery hook calls our getAllMemes Query when the component mounts. It also caches the result for us, as well as automatically re-fetching whenever we add a new Meme to our DB via createMeme. This means our page will reload automatically whenever a new meme is generated.
    2. The useAuth hook allows us to fetch info about our logged in user. If the user isn’t logged in, we force them to do so before they can generate a meme.

    These are really cool Wasp features that make your life as a developer a lot easier 🙂

    So go ahead now and try and generate a meme. Here’s the one I just generated:

    Image description

    Haha. Pretty good!

    Now wouldn’t it be cool though if we could edit and delete our memes? And what if we could expand the set of meme templates for our generator to use? Wouldn’t that be cool, too?

    Yes, it would be. So let’s do that.

    Part 2.

    So we’ve got ourselves a really good basis for an app at this point.

    We’re using OpenAI’s function calling feature to explain a function to GPT, and get it to return results for us in a format we can use to call that function.

    This allows us to be certain GPT’s result will be usable in further parts of our application and opens up the door to creating AI agents.

    If you think about it, we’ve basically got ourselves a really simple Meme generating “agent”. How cool is that?!

    Fetching & Updating Templates with Cron Jobs​

    To be able to generate our meme images via ImgFlip’s API, we have to choose and send a meme template id to the API, along with the text arguments we want to fill it in with.

    For example, the Grandma Finds Internet meme template has the following id:

    Image description

    But the only way for us to get available meme templates from ImgFlip is to send a GET request to https://api.imgflip.com/get_memes. And according to ImgFlip, the /get-memes endpoint works like this:

    Gets an array of popular memes that may be captioned with this API. The size of this array and the order of memes may change at any time. When this description was written, it returned 100 memes ordered by how many times they were captioned in the last 30 days

    So it returns a list of the top 100 memes from the last 30 days. And as this is always changing, we can run a daily cron job to fetch the list and update our database with any new templates that don’t already exist in it.

    We know this will work because the ImgFlip docs for the /caption-image endpoint — which we use to create a meme image — says this:

    key: template_id value: A template ID as returned by the get_memes response. Any ID that was ever returned from the get_memes response should work for this parameter…

    Awesome!

    Defining our Daily Cron Job​

    Now, to create an automatically recurring cron job in Wasp is really easy.

    First, go to your main.wasp file and add:

    job storeMemeTemplates {
      executor: PgBoss,
      perform: {
        fn: import { fetchAndStoreMemeTemplates } from "@server/workers.js",
      },
      schedule: {
        // daily at 7 a.m.
        cron: "0 7 * * *" 
      },
      entities: [Template],
    }

    This is telling Wasp to run the fetchAndStoreMemeTemplates function every day at 7 a.m.

    Next, create a new file in src/server called workers.ts and add the function:

    import axios from 'axios';

    export const fetchAndStoreMemeTemplates = async (_args: any, context: any) => {
      console.log('.... ><><>< get meme templates cron starting ><><>< ....');

      try {
        const response = await axios.get('https://api.imgflip.com/get_memes');

        const promises = response.data.data.memes.map((meme: any) => {
          return context.entities.Template.upsert({
            where: { id: meme.id },
            create: {
              id: meme.id,
              name: meme.name,
              url: meme.url,
              width: meme.width,
              height: meme.height,
              boxCount: meme.box_count,
            },
            update: {},
          });
        });

        await Promise.all(promises);
      } catch (error) {
        console.error('error fetching meme templates: ', error);
      }
    };

    You can see that we send a GET request to the proper endpoint, then we loop through the array of memes it returns to us add any new templates to the database.

    Notice that we use Prisma’s upsert method here. This allows us to create a new entity in the database if it doesn’t already exist. If it does, we don’t do anything, which is why update is left blank.

    We use [Promise.all() to call that array of promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all) correctly.

    Testing​

    Now, assuming you’ve got your app running with wasp start, you will see the cron job run in the console every day at 7 a.m.

    If you want to test that the cron job is working correctly, you could run it on a faster schedule. Let’s try that now by changing it in our main.wasp file to run every minute:

    //...
      schedule: {
        // runs every minute.
        cron: "* * * * *" 
      },

    First, your terminal where you ran wasp start to start your app should output the following:

    [Server]  🔍 Validating environment variables...
    [Server]  🚀 "Username and password" auth initialized
    [Server]  Starting pg-boss...
    [Server]  pg-boss started!
    [Server]  Server listening on port 3001

    …followed shortly after by:

    [Server]  .... ><><>< get meme templates cron starting ><><>< ....

    Great. We’ve got an automatically recurring cron job going.

    You can check your database for saved templates by opening another terminal window and running:

    wasp db studio

    Image description

    Editing Memes​

    Unfortunately, sometimes GPT’s results have some mistakes. Or sometimes the idea is really good, but we want to further modify it to make it even better.

    Well, that’s pretty simple for us to do since we can just make another call to ImgFlip’s API.

    So let’s set do that by setting up a dedicated page where we:

    • fetch that specific meme based on its id
    • display a form to allow the user to edit the meme text
    • send that info to a server-side Action which calls the ImgFlip API, generates a new image URL, and updates our Meme entity in the DB.

    Server-Side Code​

    To make sure we can fetch the individual meme we want to edit, we first need to set up a Query that does this.

    Go to your main.wasp file and add this Query declaration:

    query getMeme {
      fn: import { getMeme } from "@server/queries.js",
      entities: [Meme]
    }

    Now go to src/server/queries.ts and add the following function:

    import type { Meme, Template } from '@wasp/entities';
    import type { GetAllMemes, GetMeme } from '@wasp/queries/types';

    type GetMemeArgs = { id: string };
    type GetMemeResult = Meme & { template: Template };

    //...

    export const getMeme: GetMeme<GetMemeArgs, GetMemeResult> = async ({ id }, context) => {
      if (!context.user) {
        throw new HttpError(401);
      }

      const meme = await context.entities.Meme.findUniqueOrThrow({
        where: { id: id },
        include: { template: true },
      });

      return meme;
    };

    We’re just fetching the single meme based on its id from the database.

    We’re also including the related meme Template so that we have access to its id as well, because we need to send this to the ImgFlip API too.

    Pretty simple!

    Now let’s create our editMeme action by going to our main.wasp file and adding the following Action:

    //...

    action editMeme {
      fn: import { editMeme } from "@server/actions.js",
      entities: [Meme, Template, User]
    }

    Next, move over to the server/actions.ts file and let’s add the following server-side function:

    //... other imports
    import type { EditMeme } from '@wasp/actions/types';

    //... other types
    type EditMemeArgs = Pick<Meme, 'id' | 'text0' | 'text1'>;

    export const editMeme: EditMeme<EditMemeArgs, Meme> = async ({ id, text0, text1 }, context) => {
      if (!context.user) {
        throw new HttpError(401, 'You must be logged in');
      }

      const meme = await context.entities.Meme.findUniqueOrThrow({
        where: { id: id },
        include: { template: true },
      });

      if (!context.user.isAdmin && meme.userId !== context.user.id) {
        throw new HttpError(403, 'You are not the creator of this meme');
      }

      const memeUrl = await generateMemeImage({
        templateId: meme.template.id,
        text0: text0,
        text1: text1,
      });

      const newMeme = await context.entities.Meme.update({
        where: { id: id },
        data: {
          text0: text0,
          text1: text1,
          url: memeUrl,
        },
      });

      return newMeme;
    };

    As you can see, this function expects the id of the already existing meme, along with the new text boxes. That’s because we’re letting the user manually input/edit the text that GPT generated, rather than making another request the the OpenAI API.

    Next, we look for that specific meme in our database, and if we don’t find it we throw an error (findUniqueOrThrow).

    We check to make sure that that meme belongs to the user that is currently making the request, because we don’t want a different user to edit a meme that doesn’t belong to them.

    Then we send the template id of that meme along with the new text to our previously created generateMemeImage function. This function calls the ImgFlip API and returns the url of the newly created meme image.

    We then update the database to save the new URL to our Meme.

    Awesome!

    Client-Side Code​

    Let’s start by adding a new route and page to our main.wasp file:

    //...

    route EditMemeRoute { path: "/meme/:id", to: EditMemePage }
    page EditMemePage {
      component: import { EditMemePage } from "@client/pages/EditMemePage",
      authRequired: true
    }

    There are two important things to notice:

    1. the path includes the :id parameter, which means we can access page for any meme in our database by going to, e.g. memerator.com/meme/5
    2. by using the authRequired option, we tell Wasp to automatically block this page from unauthorized users. Nice!

    Now, create this page by adding a new file called EditMemePage.tsx to src/client/pages. Add the following code:

    import { useState, useEffect, FormEventHandler } from 'react';
    import { useQuery } from '@wasp/queries';
    import editMeme from '@wasp/actions/editMeme';
    import getMeme from '@wasp/queries/getMeme';
    import { useParams } from 'react-router-dom';
    import { AiOutlineEdit } from 'react-icons/ai';

    export function EditMemePage() {
      // http://localhost:3000/meme/573f283c-24e2-4c45-b6b9-543d0b7cc0c7
      const { id } = useParams<{ id: string }>();

      const [text0, setText0] = useState('');
      const [text1, setText1] = useState('');
      const [isLoading, setIsLoading] = useState(false);

      const { data: meme, isLoading: isMemeLoading, error: memeError } = useQuery(getMeme, { id: id });

      useEffect(() => {
        if (meme) {
          setText0(meme.text0);
          setText1(meme.text1);
        }
      }, [meme]);

      const handleSubmit: FormEventHandler<HTMLFormElement> = async (e) => {
        e.preventDefault();
        try {
          setIsLoading(true);
          await editMeme({ id, text0, text1 });
        } catch (error: any) {
          alert('Error generating meme: ' + error.message);
        } finally {
          setIsLoading(false);
        }
      };

      if (isMemeLoading) return 'Loading...';
      if (memeError) return 'Error: ' + memeError.message;

      return (
        <div className='p-4'>
          <h1 className='text-3xl font-bold mb-4'>Edit Meme</h1>
          <form onSubmit={handleSubmit}>
            <div className='flex gap-2 items-end'>
              <div className='mb-2'>
                <label htmlFor='text0' className='block font-bold mb-2'>
                  Text 0:
                </label>
                <textarea
                  id='text0'
                  value={text0}
                  onChange={(e) => setText0(e.target.value)}
                  className='border rounded px-2 py-1'
                />
              </div>
              <div className='mb-2'>
                <label htmlFor='text1' className='block font-bold mb-2'>
                  Text 1:
                </label>

                <div className='flex items-center mb-2'>
                  <textarea
                    id='text1'
                    value={text1}
                    onChange={(e) => setText1(e.target.value)}
                    className='border rounded px-2 py-1'
                  />
                </div>
              </div>
            </div>

            <button
              type='submit'
              className={`flex items-center gap-1 bg-primary-200 hover:bg-primary-300 border-2 text-black text-sm py-1 px-2 rounded ${
                isLoading ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer'
              } $}`}
            >
              <AiOutlineEdit />
              {!isLoading ? 'Save Meme' : 'Saving...'}
            </button>
          </form>
          {!!meme && (
            <div className='mt-4  mb-2 bg-gray-100 rounded-lg p-4'>
              <img src={meme.url} width='500px' />
              <div className='flex flex-col items-start mt-2'>
                <div>
                  <span className='text-sm text-gray-700'>Topics: </span>
                  <span className='text-sm italic text-gray-500'>{meme.topics}</span>
                </div>
                <div>
                  <span className='text-sm text-gray-700'>Audience: </span>
                  <span className='text-sm italic text-gray-500'>{meme.audience}</span>
                </div>
                <div>
                  <span className='text-sm text-gray-700'>ImgFlip Template: </span>
                  <span className='text-sm italic text-gray-500'>{meme.template.name}</span>
                </div>
              </div>
            </div>
          )}
        </div>
      );
    }

    Some things to notice here are:

    1. because we’re using dynamic routes (/meme/:id), we pull the URL paramater id from the url with useParams hook.
    2. we then pass that id within the getMemes Query to fetch that specific meme to edit: useQuery(getMeme, { id: id })
      1. remember, our server-side action depends on this id in order to fetch the meme from our database

    The rest of the page is just our form for calling the editMeme Action, as well as displaying the meme we want to edit.

    That’s great!

    Now that we have that EditMemePage, we need a way to navigate to it from the home page.

    To do that, go back to the Home.tsx file, add the following imports at the top, and find the comment that says {/* TODO: implement edit and delete meme features */} and replace it with the following code: 

    import { Link } from '@wasp/router';
    import { AiOutlineEdit } from 'react-icons/ai';

    //...

    {user && (user.isAdmin || user.id === memeIdea.userId) && (
      <div className='flex items-center mt-2'>
        <Link key={memeIdea.id} params={{ id: memeIdea.id }} to={`/meme/:id`}>
          <button className='flex items-center gap-1 bg-primary-200 hover:bg-primary-300 border-2 text-black text-xs py-1 px-2 rounded'>
            <AiOutlineEdit />
            Edit Meme
          </button>
        </Link>
        {/* TODO: add delete meme functionality */}
      </div>
    )}

    What’s really cool about this, is that Wasp’s Link component will give you type-safe routes, by making sure you’re following the pattern you defined in your main.wasp file.

    And with that, so long as the authenticated user was the creator of the meme (or is an admin), the Edit Meme button will show up and direct the user to the EditMemePage

    Give it a try now. It should look like this:

    Deleting Memes​

    Ok. When I initially started writing this tutorial, I thought I’d also explain how to add delete meme functionality to the app as well.

    But seeing as we’ve gotten this far, and as the entire two-part tutorial is pretty long, I figured you should be able to implement yourself by this point.

    So I’ll leave you guide as to how to implement it yourself. Think of it as a bit of homework:

    1. define the deleteMeme Action in your main.wasp file
    2. export the async function from the actions.ts file
    3. import the Action in your client-side code
    4. create a button which takes the meme’s id as an argument in your deleteMeme Action.

    If you get stuck, you can use the editMeme section as a guide. Or you can check out the finished app’s GitHub repo for the completed code!

    Conclusion

    There you have it! Your own instant meme generator 🤖😆

    BTW, If you found this useful, please show us your support by giving us a star on GitHub! It will help us continue to make more stuff just like it.

    https://res.cloudinary.com/practicaldev/image/fetch/s--tnDxibZC--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_66%2Cw_800/https://res.cloudinary.com/practicaldev/image/fetch/s--OCpry2p9--/c_limit%252Cf_auto%252Cfl_progressive%252Cq_66%252Cw_800/https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bky8z46ii7ayejprrqw3.gif

    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/10/04/contributing-open-source-land-a-job.html b/blog/2023/10/04/contributing-open-source-land-a-job.html index 3257106db7..9f50e6178d 100644 --- a/blog/2023/10/04/contributing-open-source-land-a-job.html +++ b/blog/2023/10/04/contributing-open-source-land-a-job.html @@ -18,16 +18,16 @@ - - - + + +

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

    · 10 min read
    Vinny

    TL;DR​

    How to Open-Source In this article, we’re going to see how open-source can change your career for the better and get you out of the Skill Paradox — a point in which the skills you need to land a job are generally acquired after you get a job.

    Besides that, we’ll check how you can start contributing to different open-source projects and get on the hype train of Hacktoberfest while also learning some important topics on handling feedbacks and showcasing your contributions.

    1. Introduction​

    Are you a beginner developer that lacks certain skills needed to land a job? But you feel that you could only gain those skills on the job itself? If you answered “yes”, then you’re stuck in situation that I would call as the “skill paradox” — where you need skills to get a job, but those skills are the ones you would get if you had a job. It can generate a lot of stress and frustration when you start to realize that some skills cannot be obtained while working only on side hustles and therefore, you cannot learn only by yourself, but they’re generally required for job positions.

    Collaboration and teamwork, learning how to code review (giving and receiving feedback), and getting started with bigger and existing codebases are things that cannot be taught while you work on some little projects. While, of course, you can learn those skills while getting a job in tech, sometimes those skills are necessary for you to get a job, making you stay in some kind of limbo where you need some skills to get a job, and those skills are precisely the ones you would get after the job.

    In those cases, there’s still a way out of the limbo: you can contribute to open-source communities. Besides the value you are generating for the whole ecosystem, this can be an amazing selling point for your career and, since Hacktoberfest is already around the corner, will be a great way to win a t-shirt or plant a tree too!

    Now, let’s begin by teaching you how to actually do this.

    2. First steps on Open-Source Contribution​

    2.1. Finding a project​

    First of all, we need to choose a project. If you’re a beginner, you’re probably looking for projects that have a few characteristics:

    • It’s actively maintained.
    • Has an open-source license that we can modify and use freely.
    • It’s not insanely big (since these projects can have some really hard things to accomplish before submitting something).
    • It must have good documentation on how to contribute.
    • It must have well-characterized issues in order for you to search for something (in the case that you haven’t found the problem itself).

    If you have matches in all of these points (or at least three of them), you’re good to go!

    Throughout this article, I’m going to use our own repo, Wasp Full-stack Framework, since it gathers all the characteristics necessary for a good open-source repository.

    So, let me show you how to find all these characteristics:

    • It’s actively maintained and the owners of the repo reply and care for the issues!
      • In the case of Wasp’s repo, the last commit was 13 hours ago, so, there’s definitely signs of life here!

    Last commit

    • It’s not insanely big → Comparing an exaggerated example with the Linux repo (if you check it, you’ll see that all pull requests there usually take a lot of time to be merged since the project is so big)

    Linux repo

    • It’s good to have a documentation on how to contribute
      • Searching for the docs, I found a file called CONTRIBUTING.md (which is a common name standard for contribution guidelines) and when we open it up:

    Contributing guidelines

    We have a whole documentation on how to start with things! Awesome!

    • It’s good to have well characterized issues in order for you to search for something

    Issues

    Searching for the issues, we can easily see that they’re all labeled and that will help us A TON!

    2.2. Searching for Issues​

    Great! Now that we have already chosen where we are going to contribute, let’s dive into the issues and search for something we want to do!

    When searching for issues, the labels do us a great favor by already explicitly identifying all issues that can be good for newcomers! If you’re a beginner, good first issues and documentation are excellent labels for you to search for!

    Good labels to search for

    Issues on the repo labeled

    Opening the first issue, we can see that someone already manifested interest on it! So, since someone has already manifested interest in that one, let’s search for another one!

    The first issue

    Finding another issue — it doesn’t look like anyone is working on the one below, so we can take it ourselves!

    Finding another issue

    By the way, it's of absolute importance that, when you find an issue, you comment and set yourself as assignee in order to let other people know that you're going to take the task at hand!

    Communicating

    In this case, GitHub is a great platform for us to discuss, but sometimes authors can be hard to find. In these cases, search for a link or a way to contact them directly (in the case of Wasp, they have a Discord server, for example). Communicating your way through is really important to get things sorted out, and if you’re unsure of how to communicate well with people, you can read this other article here and start to get the hang of it!

    3. Guidelines for Contributing to Open-Source Projects​

    3.1. Reading the guidelines and writing some code​

    Now that we have selected a repo, an issue to work on and communicated with the authors, it’s time to check the guidelines for making Pull Requests (if you don’t know what this means, it’s basically a request to merge your modifications to the codebase, you can check some more basic git terms here too). Sometimes, these guidelines are WAY too hard and sometimes they don’t even exist (that’s an awesome first issue actually), anyways look it up and see if you find something!

    You can check Wasp’s contributing guidelines here if you want to read it yourself! After reading it, it’s time to code the solution and get along with it.

    Since the intent of this article is not to actually show the solving per se, I’ll skip this part and keep talking about the process itself.

    3.2 Handling Code Reviews and Feedback​

    It’s not rare that when we code things up (especially in open-source projects), there will be some problems. Code reviews and feedback are an amazing way for us to get the bigger picture and improve our code quality, so let’s check on how to properly read and answer code reviews and feedback.

    We’re generally used to receiving criticism in a harsh way, so, when someone approaches you with feedbacks, we generally move into our defense zone. Unfortunately, these cases can teach you the wrong things as it’s generally a good way to think of feedbacks as gifts! Someone spent some time writing (or speaking) things in order for you get even better on what you’re trying to accomplish.

    This does not mean that all feedback is well-made or that people will always provide great feedback. Sometimes, people can be harsh. However, as you receive more and more feedbacks, you will develop a sense of which feedbacks are genuinely meant to help you improve and which are simply baseless criticism. It is crucial to be open to receiving constructive feedbacks and not take them personally.

    Let’s see an example of code review and feedback here:

    Code Review Example

    This is great feedback! It expresses the author’s opinion without being harsh and also suggests what to make in order to be perfect! The best way to answer this is simply:

    • Thanking for the feedback
    • Saying your opinion (agree or disagree) when it makes sense
    • Work on it!

    Showcasing Contributions​

    After all that work, it’s time for us to showcase our contributions! Document it all. GitHub (or other git platforms), personal portfolio sites, LinkedIn, and other means of reaching people have become as important as resumes nowadays, so it’s really nice to have some statistics and data to display on:

    • What open-source projects have you worked on? Try to think of this as writing a story. First, start by giving the initial context of the project and how it’s revelatory.
    • How you contributed: Then, give the context of what you made, documentation, code, and problems you solved in general. Don’t forget to not focus a lot on the technical side since the person who could be reading this may not be technical.
    • How big was the impact? Talk about how this affected the ecosystem; it can be as big or as small as you like. Never neglect the impact that changing documentation can have (remember that for us, programmers, the documentation is our source of truth, and fixes there are greatly appreciated).

    Don’t forget to utilize the opportunity to engage with other developers and communities, make it so in order to get new connections and even greater opportunities later on!

    Now that the theory is set, let’s check a few examples on how I would showcase a few of my contributions:

    Case 1 - A big contribution​

    One of the ways to describe a big contribution is like this:

    I made a few big contributions to a project called Coolify, which was an open-source Heroku alternative. I refactored a lot of the UI, making it cleaner and more consistent throughout the application. Currently, more than 9000 instances are installed, and the UI affects all of them! You can check out the contributions here.

    Of course, you can make this text as long or as short as you want, entering more detail about how this contribution was made and what exactly you did, but for this article, this is enough for you to get a general idea.

    Case 2- A small contribution​

    One way to describe a small contribution is like this:

    I made a small change to the new documentation for Sequelize! I was just scrolling through the documentation and found this mistake that could lead others to weird debugging sessions, so as soon as I found it, I submitted a PR for them! You can check out the contribution here!

    Conclusion​

    So, a lot was said, let’s make a quick recap on how to do contributions and how to showcase them:

    • First of all, find a repo! If you don’t have any in mind, there loads of lists (like this one) that recommend some repos for you to take a look
    • Search for an issue that is not being made and you can work on it, if you’re beginner, check for documentation and good first issue labels
    • Comment and communicate that you’re going to fix the issue - take the opportunity to talk and get to know other developers
    • Code, get you PR reviewed and ready to merge after the feedbacks
    • Merge and showcase your contributions, showing that they are your way out of the Skill Paradox

    How to Open-Source

    The above steps can give you a really powerful experience in software engineering (which usually happens only when you’re already hired by a company). This is an awesome way to get some recognition while improving the open-source community — giving back to other developers and getting yourself out of the Skill Paradox!

    And you? Have you contributed to open-source? Let me know in the comments below, and let’s share some experiences!

    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/10/12/on-importance-of-naming-in-programming.html b/blog/2023/10/12/on-importance-of-naming-in-programming.html index 26c10620b4..f785f965cf 100644 --- a/blog/2023/10/12/on-importance-of-naming-in-programming.html +++ b/blog/2023/10/12/on-importance-of-naming-in-programming.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ Sounds simple, but it is really not!

    Let’s take a look at a couple of examples.

    Example #1

    // Given first and last name of a person, returns the
    // demographic statistics for all matching people.
    async function demo (a, b) {
      const c = await users(a, b);
      return [
        avg(c.map(a => a.info[0])),
        median(c.map(a => a.info[1]))
      ];
    }

    What is wrong with this code?

    1. The name of the function demo is very vague: it could stand for “demolish”, or as in “giving a demo/presentation”, … .
    2. Names a, b, and c are completely uninformative.
    3. a is reused in lambda inside the map, shadowing the a that is a function argument, confusing the reader and making it easier to make a mistake when modifying the code in the future and reference the wrong variable.
    4. The returned object doesn’t have any info about what it contains, instead, you need to be careful about the order of its elements when using it later.
    5. The name of the field .info in the result of a call to users() function gives us no information as to what it contains, which is made further worse by its elements being accessed by their position, also hiding any information about them and making our code prone to silently work wrong if their ordering changes.

    Let’s fix it:

    async function fetchDemographicStatsForFirstAndLastName (
      firstName, lastName
    ) {
      const users = await fetchUsersByFirstAndLastName(
        firstName, lastName
      );
      return {
        averageAge: avg(users.map(u => u.stats.age)),
        medianSalary: median(users.map(u => u.stats.salary))
      };
    }

    What did we do?

    1. The name of the function now exactly reflects what it does, no more no less. fetch in the name even indicates it does some IO (input/output, in this case fetching from the database), which can be good to know since IO is relatively slow/expensive compared to pure code.
    2. We made other names informative enough: not too much, not too little.
      • Notice how we used the name users for fetched users, and not something longer like usersWithSpecifiedFirstAndLastName or fetchedUsers: there is no need for a longer name, as this variable is very local, short-lived, and there is enough context around it to make it clear what it is about.
      • Inside lambda, we went with a single-letter name, u, which might seem like bad practice. But, here, it is perfect: this variable is extremely short-lived, and it is clear from context what it stands for. Also, we picked specifically the letter u for a reason, as it is the first letter of user, therefore making that connection obvious.
    3. We named values in the object that we return: averageAge and medianSalary. Now any code that will use our function won’t need to rely on the ordering of items in the result, and also will be easy and informative to read.

    Finally, notice how there is no comment above the function anymore. The thing is, the comment is not needed anymore: it is all clear from the function name and arguments!

    Example #2

    // Find a free machine and use it, or create a new machine
    // if needed. Then on that machine, set up the new worker 
    // with the given Docker image and setup cmd. Finally,
    // start executing a job on that worker and return its id.
    async function getJobId (
      machineType, machineRegion,
      workerDockerImage, workerSetupCmd,
      jobDescription
    ) {
      ...
    }

    In this example, we are ignoring the implementation details and will focus just on getting the name and arguments right.

    What is wrong with this code?

    1. The function name is hiding a lot of details about what it is doing. It doesn’t mention at all that we have to procure the machine or set up the worker, or that function will result in the creation of a job that will continue executing somewhere in the background. Instead, it gives a feeling that we are doing something simple, due to the verb get: we are just obtaining an id of an already existing job. Imagine seeing a call to this function somewhere in the code: getJobId(...) → you are not expecting it to take long or do all of the stuff that it really does, which is bad.

    Ok, this sounds easy to fix, let’s give it a better name!

    async function procureFreeMachineAndSetUpTheDockerWorkerThenStartExecutingTheJob (
      machineType, machineRegion,
      workerDockerImage, workerSetupCmd,
      jobDescription
    ) {
      ...
    }

    Uff, that is one long and complicated name. But the truth is, that we can’t really make it shorter without losing valuable information about what this function does and what we can expect from it. Therefore, we are stuck, we can’t find a better name! What now?

    The thing is, you can't give a good name if you don't have clean code behind it. So a bad name is not just a naming mishap, but often also an indicator of problematic code behind it, a failure in design. Code so problematic, that you don’t even know what to name it → there is no straightforward name to give to it, because it is not a straightforward code!

    Bad name is hiding bad code

    In our case, the problem is that this function is trying to do too much at once. A long name and many arguments are indicators of this, although these can be okay in some situations. Stronger indicators are the usage of words “and” and “then” in the name, as well as argument names that can be grouped by prefixes (machine, worker).

    The solution here is to clean up the code by breaking down the function into multiple smaller functions:

    async function procureFreeMachine (type, region) { ... }
    async function setUpDockerWorker (machineId, dockerImage, setupCmd) { ... }
    async function startExecutingJob (workerId, jobDescription) { ... }

    What is a good name?

    But let’s take a step back - what is a bad name, and what is a good name? What does that mean, how do we recognize them?

    Good name doesn’t misdirect, doesn’t omit, and doesn’t assume.

    A good name should give you a good idea about what the variable contains or function does. A good name will tell you all there is to know or will tell you enough to know where to look next. It will not let you guess, or wonder. It will not misguide you. A good name is obvious, and expected. It is consistent. Not overly creative. It will not assume context or knowledge that the reader is not likely to have.

    Also, context is king: you can’t evaluate the name without the context in which it is read. verifyOrganizationChainCredentials could be a terrible name or a great name. a could be a great name or a terrible name. It depends on the story, the surroundings, on the problem the code is solving. Names tell a story, and they need to fit together like a story.

    Examples of famous bad names

    • JavaScript
      • I was the victim of this bad naming myself: my parents bought me a book about JavaScript while I wanted to learn Java.
    • HTTP Authorization header
    • Wasp-lang:
      • This one is my fault: Wasp is a full-stack JS web framework that uses a custom config language as only a small part of its codebase, but I put -lang in the name and scared a lot of people away because they thought it was a whole new general programming language!

    How to come up with a good name

    Don’t give a name, find it​

    The best advice is maybe not to give a name, but instead to find out a name. You shouldn’t be making up an original name, as if you are naming a pet or a child; you are instead looking for the essence of the thing you are naming, and the name should present itself based on it. If you don’t like the name you discovered, it means you don’t like the thing you are naming, and you should change that thing by improving the design of your code (as we did in the example #2).

    You shouldn't name your variables the same way you name your pets, and vice versa

    Things to look out for when figuring out a name​

    1. First, make sure it is not a bad name :). Remember: don’t misdirect, don’t omit, don’t assume.
    2. Make it reflect what it represents. Find the essence of it, capture it in the name. Name is still ugly? Improve the code. You have also other things to help you here → type signature, and comments. But those come secondary.
    3. Make it play nicely with the other names around it. It should have a clear relation to them - be in the same “world”. It should be similar to similar stuff, opposite to opposite stuff. It should make a story together with other names around it. It should take into account the context it is in.
    4. Length follows the scope. In general, the shorter-lived the name is, and the smaller its scope is, the shorter the name can/should be, and vice versa. This is why it can be ok to use one-letter variables in short lambda functions. If not sure, go for the longer name.
    5. Stick to the terminology you use in the codebase. If you so far used the term server, don’t for no reason start using the term backend instead. Also, if you use server as a term, you likely shouldn't go with frontend: instead, you will likely want to use client, which is a term more closely related to the server.
    6. Stick to the conventions you use in the codebase. Examples of some of the conventions that I often use in my codebases:
      • prefix is when the variable is Bool (e.g. isAuthEnabled)
      • prefix ensure for the functions that are idempotent, that will do something (e.g allocate a resource) only if it hasn’t been set up so far (e.g. ensureServerIsRunning).

    The simple technique for figuring out a name every time​

    If you are ever having trouble coming up with a name, do the following:

    1. Write a comment above the function/variable where you describe what it is, in human language, as if you were describing it to your colleague. It might be one sentence or multiple sentences. This is the essence of what your function/variable does, what it is.
    2. Now, you take the role of the sculptor, and you chisel at and shape that description of your function/variable until you get a name, by taking pieces of it away. You stop when you feel that one more hit of your imagined chisel at it would take too much away.
    3. Is your name still too complex/confusing? If that is so, that means that the code behind is too complex, and should be reorganized! Go refactor it.
    4. Ok, all done → you have a nice name!
    5. That comment above the function/variable? Remove everything from it that is now captured in the code (name + arguments + type signature). If you can remove the whole comment, great. Sometimes you can’t, because some stuff can’t be captured in the code (e.g. certain assumptions, explanations, examples, …), and that is also okay. But don’t repeat in the comment what you can say in the code instead. Comments are a necessary evil and are here to capture knowledge that you can’t capture in your names and/or types.

    Don’t get overly stuck on always figuring out the perfect name at the get-go → it is okay to do multiple iterations of your code, with both your code and name improving with each iteration.

    Reviewing code with naming in mind

    Once you start thinking a lot about naming, you will see how it will change your code review process: focus shifts from looking at implementation details to looking at names first.

    When I am doing a code review, there is one predominant thought I will be thinking about: “Is this name clear?”. From there, the whole review evolves and results in clean code.

    Inspecting a name is a single point of pressure, that untangles the whole mess behind it. Search for bad names, and you will sooner or later uncover the bad code if there is some.

    Further reading

    If you haven’t yet read it, I would recommend reading the book Clean Code by Robert Martin. It has a great chapter on naming and also goes much further on how to write code that you and others will enjoy reading and maintaining.

    Also, A popular joke about naming being hard.

    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/10/13/wasp-launch-week-four.html b/blog/2023/10/13/wasp-launch-week-four.html index 412b47a358..6d1c02b99a 100644 --- a/blog/2023/10/13/wasp-launch-week-four.html +++ b/blog/2023/10/13/wasp-launch-week-four.html @@ -18,14 +18,14 @@ - - - + + +

    Wasp Launch Week #4: Waspolution

    · 5 min read
    Matija Sosic

    Launch Week 4 is coming

    We're back! Beginning of the October was both the craziest and busiest time we've ever had at Wasp - we ended up on GitHub Trending (almost at 7,000 stars - thank you🙏), MAGE (our GPT web app generator) exploded with 20,000 apps created and more people than ever used Wasp!

    Crazily enough, we've even had a first startup project made in Wasp that has been acquired (GPT-powered, of course)! 💸🐝💸

    To top it all off, we have a new launch week incoming that brings a ton of new exciting product updates! If this is your first rodeo, check out our previous launches:

    What's this launch all about?​

    As you might have noticed, each of our launches comes with a specific theme. We've come a long way since our first launch week, Beta release, which moved Wasp from a prototype to a real, working framework. In the previous two launch weeks we've added plenty of new features and unlocked functionalities you couldn't have used before (e.g. email sending, async jobs, ...).

    This time we kept introducing new features, but we also realised there are many opportunities to make developers' lives even easier. That's why the theme of this launch week stems from "Evolution" - Wasp is now well set on its way, lies on the solid foundations with a strong community behind it and keeps naturally evolving!

    Growing up
    Wasp from this launch onwards.

    Enough chit-chat - let's see what will go down next week! We'll present a new feature (or more of them) every day. To stay in the loop follow us on Twitter/X (@WaspLang) and join our community on Wasp Discord!

    Launch party 🚀🎉​

    launch event 3 - screenshot
    A bit of the atmosphere from LW3 launch party!

    As it is a tradition by now, we'll kick things off with a launch party on our Discord! You will be able to meet the team and be the first one to learn about the new features we'll be revealing for the rest of the week. We'll also answer community questions, discuss plans for the future, and of course, hand out some sweet swag (finally get your hands on that Da Boi plushie)!

    The party starts at 11 am EDT / 5 pm CET - sign up here and make sure to mark yourself as "interested"!

    launch event - how to join

    Monday: I am Speed 🚄​

    Why waste time
    We think the same, but about keystrokes.

    We all know that developer productivity is a hot topic these days. At the end of the day, why waste time use many keystroke when few do trick?

    That's exactly what we will feature on Monday! Wasp is already famous for its brevity and prototyping speed, which is powered by its high-level configuration language, but we found a way to make things even simpler!

    When: Monday, October 16 2023

    Tuesday: Safety first 👷​

    Realtime

    In every industry they have strict safety protocols - we believe programming should be no different! Especially when it comes to types - imagine if you had a piece of data running around your application, without even knowing what it looks like!? No sir, not under my watch ⬇️⌚️.

    When: Tuesday, October 17 2023

    Wednesday: Wasp x AI x ...base 🤖⚡️​

    Power Rangers

    The best things happen when you combine multiple amazing things together - and that's exactly what we did! I don't want to spoil too much, but let's just say it has become much easier to do a certain similarity search with Wasp 😉.

    I don't want to overhype it, but it might be one of the coolest things you've seen so far - see you on Wednesday!

    When: Wednesday, October 18 2023

    Thursday: A glimpse into the future 🛸​

    World if everyone used Wasp for web development

    Although there is a plenty of work to refine the existing features and polish the overal developer experience, we still always have our eyes on the future and take time to experiment. This is what we will present here - a really cool feature that is possible due to the Wasp's unique approach, that will illuminate a lot posibilities for the future!

    When: Thursday, October 19 2023

    Friday: Polish 💅​

    Wax on, Wax off

    Sometimes, the best thing you can do is take care of what you already have! As we mentioned in the intro, Wasp is becoming all about DX, feature completeness and elegance of use. And this is what we will demonstrate today!

    When: Friday, October 20 2023

    Monday: SaaS-a-thon!​

    Hacking

    As the ancient scrolls say, every launch week must end with a hackathon, and this is no exception! We'll share more details soon, but as the title says, we'll equip you as well as possible to create a SaaS of your dreams in no time!

    When: Monday, October 23 2023

    Recap​

    • We are kicking off Launch Week #4 on Mon, Oct 16, at 11am EDT / 5pm CET - make sure to register for the event!
    • Launch Week #4 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 SaaS-a-thon - get your keyboards warmed up and ready to roll!
    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/11/21/guide-windows-development-wasp-wsl.html b/blog/2023/11/21/guide-windows-development-wasp-wsl.html index 1125192efa..52cbd8f703 100644 --- a/blog/2023/11/21/guide-windows-development-wasp-wsl.html +++ b/blog/2023/11/21/guide-windows-development-wasp-wsl.html @@ -18,15 +18,15 @@ - - - + + +

    A Guide to Windows Development with Wasp & WSL

    · 10 min read
    Boris Martinović

    WSL Guide Banner

    If you are having a hard time with Wasp development on Windows, don't be afraid! We will go through all necessary steps to set up your dev environment and get you started with Wasp development in Windows in no time.

    What is WSL and why should I be interested in it?​

    Windows Subsystem for Linux (or WSL) lets developers run a fully functional and native GNU/Linux environment directly on Windows. In other words, we can run Linux directly without using a virtual machine or dual-booting the system.

    The first cool thing about it is that WSL allows you to never switch OS’s, but still have the best of both worlds inside your OS. What does that mean for us regular users? When you look at the way WSL works in practice, it can be considered a Windows feature that runs a Linux OS directly inside Windows 10 or 11, with a fully functional Linux file system, Linux command line tools, and Linux GUI apps (really cool, btw). Besides that, it uses much fewer resources for running when compared to a virtual machine and also doesn’t require a separate tool for creating and managing those virtual machines.

    WSL is mainly catered to developers, so this article will be focused on developer usage and how to set up a fully working dev environment with VS Code. Inside this article, we’ll go through some of the cool features and how they can be used in practice. Plus, the best way to understand new things is to actually start using them.

    Installing WSL on the Windows operating system​

    In order to install WSL on your Windows, first enable Hyper-V architecture is Microsoft’s hardware virtualization solution. To install it, right-click on the Windows Terminal/Powershell and open it in Administrator mode.

    Image description

    Then, run the following command:

    Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

    That will ensure that you have all the prerequisites for the installation. Then, open the Powershell (best done in Windows Terminal) in the Administrator mode. Then, run

    wsl —install

    There is a plethora of Linux distributions to be installed, but Ubuntu is the one installed by default. This guide will feature many console commands, but most of them will be a copy-paste process.

    If you have installed Docker before, there is a decent chance that you have WSL 2 installed on your system already. In that case, you will get a prompt to install the distribution of your choice. Since this tutorial will be using Ubuntu, I suggest running.

     wsl --install -d Ubuntu

    After installing Ubuntu (or another distro of your choice), you will enter your Linux OS and be prompted with a welcome screen. There, you will enter some basic info. First, you will enter your username and after that your password. Both of those will be Linux-specific, so you don’t necessarily have to repeat your Windows credentials. After we’ve done this, the installation part is over! You have successfully installed Ubuntu on your Windows machine! It still feels weird to say this, right?

    Cool WSL featues to help you along the way​

    But before we get down to our dev environment setup, I want to show you a couple of cool tricks that will make your life easier and help you understand why WSL is actually a game-changer for Windows users.

    The first cool thing with WSL is that you don’t have to give up the current way of managing files through Windows Explorer. In your sidebar in Windows Explorer, you can find the Linux option now right under the network tab.

    Image description

    From there, you can access and manage your Linux OS’s file system directly from the Windows Explorer. What is really cool with this feature is that you can basically copy, paste, and move files between different operating systems without any issues, which opens up a whole world of possibilities. Effectively, you don’t have to change much in your workflow with files and you can move many projects and files from one OS to another effortlessly. If you download an image for your web app on your Windows browser, just copy and paste it to your Linux OS.

    Image description

    Another very important thing, which we will use in our example is WSL2 virtual routes. As you now have OS inside your OS, they have a way of communicating. When you want to access your Linux OS’s network (for example, when you want to access your web app running locally in Linux), you can use ${PC-name}.local. For me, since my PC name is Boris-PC, my network address is boris-pc.local. That way you don’t have to remember different IP addresses, which is really cool. If you want your address for whatever reason, you can go to your Linux distro’s terminal, and type ipconfig. Then, you can see your Windows IP and Linux’s IP address. With that, you can communicate with both operating systems without friction.

    Image description

    The final cool thing I want to highlight is Linux GUI apps. It is a very cool feature that helps make WSL a more attractive proposal for regular users as well. You can install any app you want on your Linux system using popular package managers, such as apt (default on Ubuntu) or flatpak. Then you can launch them as well from the command line and the app will start and be visible inside your Windows OS. But that can cause some friction and is not user-friendly. The really ground-breaking part of this feature is that you can launch them directly from your Windows OS without even starting WSL yourself. Therefore, you can create shortcuts and pin them to the Start menu or taskbar without any friction and really have no need to think about where your app comes from. For the showcase, I have installed Dolphin File Manager and run it through Windows OS. You can see it action below side by side with Windows Explorer.

    Image description

    Getting started with development on WSL​

    After hearing all about the cool features of WSL, let’s slowly get back on track with our tutorial. Next up is setting up our dev environment and starting our first app. I’ll be setting up a web dev environment and we’ll use Wasp as an example.

    If you aren’t familiar with it, Wasp is a Rails-like framework for React, Node.js, and Prisma. It’s a fast and easy way to develop and deploy your full-stack web apps. For our tutorial, Wasp is a perfect candidate, since it doesn’t support Windows development natively, but only through WSL as it requires a Unix environment.

    Let’s get started with installing Node.js first. NVM is the best tool for versioning Node.js, so we want to start with both Node.js and NVM installation.

    But first things first, let’s start with Node.js. In WSL, run:

    sudo apt install nodejs

    in order to install Node on your Linux environment. Next up is NVM. I suggest going to https://github.com/nvm-sh/nvm and getting the latest install script from there. The current download is:

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

    After this, we have both Node.js and NVM set up in our system.

    Installing Wasp​

    Next up is installing Wasp on our Linux environment. Wasp installation is also pretty straightforward and easy. So just copy and paste this command:

    curl -sSL https://get.wasp-lang.dev/installer.sh | sh

    and wait for the installer to finish up its thing. Great! But, if you did your WSL setup from 0, you will notice the following warning underneath: It looks like '/home/boris/.local/bin' is not on your PATH! You will not be able to invoke wasp from the terminal by its name.

    Image description

    Let’s fix this quickly. In order to do this, let’s run

     code ~/.profile

    If we don’t already have VS Code, it will automatically set up everything needed and boot up so you can add the command to the end of your file. It will be different for everyone depending on their system name. For example, mine is:

    export PATH=$PATH:/home/boris/.local/bin

    Setting up VS Code​

    After setting up Wasp, we want to see how to run the app and access it from VS Code. Under the hood, you will still be using WSL for our development, but we’ll be able to use our VS Code from Host OS (Windows) for most of the things.

    Image description

    To get started, download the WSL extension to your VS Code in Windows. Afterward, let’s start a new Wasp project to see how it works in action. Open your VS Code Command Palette (ctrl + shift + P) and select the option to “Open Folder in WSL”.

    Image description

    The folder that I have opened is

    \\wsl.localhost\Ubuntu\home\boris\Projects

    That is the “Projects” folder inside my home folder in WSL. There are 2 ways for us to know that we are in WSL: The top bar and in the bottom left corner of VS Code. In both places, we should see the text WSL: Ubuntu, as shown on screenshots.

    Image description

    Image description

    Once inside this folder, I will open a terminal. It will also be already connected to the proper folder in WSL, so we can get down to business! Let’s run the

    wasp new

    command to create a new Wasp application. I have chosen the basic template, but you are free to create a project of your choosing, e.g. SaaS starter with GPT, Stripe and more preconfigured. As shown in the screenshot, we should change the current directory of our project to the proper one and then run our project with it.

    wasp start

    Image description

    And just like that, a new screen will open on my Windows machine, showcasing that my Wasp app is open. Cool! My address is still the default localhost:3000, but it is being run from the WSL. Congratulations, you’ve successfully started your first Wasp app through WSL. That wasn’t hard, was it?

    Image description

    For our final topic, I want to highlight Git workflow with WSL, as it is relatively painless to set up. You can always do the manual git config setup, but I have something cooler for you: Sharing credentials between Windows and WSL. To set up sharing Git credentials, we have to do the following. In Powershell (on Windows), configure the credential manager on Windows.

    git config --global credential.helper wincred

    And let’s do the same inside WSL.

    git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

    This allows us to share our Git username and password. Anything set up in Windows will work in WSL (and vice-versa) and we can use Git inside WSL as we prefer (via VS Code GUI or via shell).

    Conclusion​

    Through our journey here, we have learned what WSL is, how it can be useful for enhancing our workflow with our Windows PC, but also how to set up your initial development environment on it. Microsoft has done a fantastic job with this tool and has really made Windows OS a much more approachable and viable option for all developers. We went through how to install the dev tools needed to kickstart development and how to get a handle on a basic dev workflow. Here are some important links if you want to dive deeper into the topic:

    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/12/05/writing-rfcs.html b/blog/2023/12/05/writing-rfcs.html index f22c6f5770..97e795fcc7 100644 --- a/blog/2023/12/05/writing-rfcs.html +++ b/blog/2023/12/05/writing-rfcs.html @@ -18,14 +18,14 @@ - - - + + +

    On the Importance of RFCs in Programming

    · 14 min read
    Matija Sosic

    Imagine you’ve been tasked to implement a sizeable new feature for the product you’re working on. That’s the opportunity you’ve been waiting for - everybody will see what a 10x developer you are! You open a list of the coolest new libraries and design patterns you’ve wanted to try out and get right into it, full “basement” mode. One week later, you victoriously emerge and present your perfect pull request!

    But then, the senior dev in a team immediately rejects it - “Too complex, you should have simply used library X and reused Y.”. What!? Before you know it, you’re looking at 100 comments on your PR and days of refactoring to follow.

    If only there were a way of knowing about X and Y before implementing everything. Well, it is, and it’s called RFC!

    The revelation of RFC

    We’ll learn about it through the example of RFC about implementing an authentication system in a web framework Wasp. Wasp is a full-stack web framework built on top of React, Node.js and Prisma. It is used by MAGE, a free GPT-powered codebase generator, which has been used to start over 30,000 applications.

    Let's dive in!

    So, what is an RFC?​

    RFC (Request For Comments) is, simply explained, a document proposing a codebase change to solve a specific problem. Its main purpose is to find the best way to solve a problem, as a team effort, before the implementation starts. RFCs were first adopted by the open-source community, but today, they are used in almost any type of developer organization.

    RFC overivew
    A simplified schema of a typical RFC.

    There are other names for this type of document you might encounter in the industry, like TDD (Technical Design Document) or SDD (Software Design Document). Some people argue over the distinction between them, but we won’t.

    Fun fact: RFCs were invented by IETF (Internet Engineering Task Force), the engineering organization behind some of the most important internet standards and protocols we use today, like TCP/IP! Not too shabby, right?

    When should I write RFC, and when can I skip it?​

    RFC overivew

    So, why bother writing about what you will eventually code, instead of saving time and simply doing it? If you’re dealing with a bug or a relatively simple feature, where it’s very clear what you must do and doesn’t affect project structure, then there’s no need for an RFC - fire up that IDE and get cracking!

    But, if you are introducing a completely new concept (e.g., introducing a role-based permission system) or altering the project’s architecture (e.g., adding support for running background jobs), then you might want to take a step back before typing git checkout -b my-new-feature and diving into that sweet coding zone.

    All the above being said, sometimes it's not easy to figure out if you should write an RFC or not. Maybe it’s a more prominent feature, but you’ve done something similar before, and you’ve already mapped everything out in your head and pretty much have no questions. To help with that, here’s a simple heuristic I like to use: Is there more than one obvious way to implement this feature? Is there a new library/service we have to pick? If the answer to both of these is “No", you probably don’t need an RFC. Otherwise, there’s a discussion to be had, and RFC is the way to do it.

    RFC decision flowchart

    It sounds useful. But what’s in it for me?​

    We’ve established how to decide when to write an RFC, but here is also why you should do it:

    • You will organize your thoughts and get clarity. If you’ve decided to write an RFC, that means you’re dealing with a non-trivial, open-ended problem. Writing things down will help distill your thoughts and have an objective look at them.
    • You will learn more than if you just jumped into coding. You will give yourself space to explore different approaches and oftentimes discover something you haven’t even thought of initially.
    • You will crowdsource your team’s knowledge. By asking your team for feedback (hence Request For Comments), you will get a complete picture of the problem you’re solving and fill in any remaining gaps.
    • You will advance your team’s understanding of the codebase. By collaborating on your RFC, everybody on the team will understand what you’re doing and how you eventually did it. That means next time somebody has to touch that part of the code, they will need to ask you much less questions (=== more uninterrupted coding time!).
    • PR reviews will go much smoother. Remember that situation from the beginning of this article, when your PR got rejected as "too complex"? That’s because the reviewer is missing the context, and you made a sizeable change without a previous buy-in from the rest of the team. By writing an RFC first, you’ll never encounter this type of situation again.
    • Your documentation is already 50% done! To be clear, RFC is not the final documentation, and you cannot simply point to it, but you can likely reuse a lot - images, diagrams, paragraphs, etc.

    Wow, this sounds so good that I want to come up with a new feature right now just so I can write an RFC for it! Joke aside, going through with the RFC first makes the coding part so much more enjoyable - you know exactly what you need to do, and you don’t need to question your approach and how it will be received once you create that PR.

    Ok, ok, I’m sold! So, how do I go about writing one?​

    Glad you asked! Many different formats are being used, more or less formal, but I prefer to keep it simple. RFCs that we write at Wasp don’t follow a strict format, but there are some common parts:

    • Metadata - Title, date, reviewers, etc…
    • Problem / Goal
    • Proposed solution (or more of them)
    • Implementation overview
    • Remarks / open questions

    That’s pretty much the gist of it! Each of these can be further broken down and refined, but this is the basic outline you can start with.

    Let’s now go over each of these and see what they look like in practice, on our Authentication in Wasp example.

    Metadata ⌗​

    RFC metadata

    This one is pretty self-explanatory - you will want to track some basic info about your RFCs - status, date of creation, etc.

    Some templates also explicitly list the reviewers and the status of their “approval” of the RFC, similar to the PR review process - we don’t have it since we’re a small team where communication happens fast, but it can be handy for larger teams where not everybody knows everybody, and you want to have a bit more of a process in place (e.g. when mentoring junior developers).

    RFC reviewer status
    Some RFCs require explicit approval by each reviewer.

    The problem 🤔​

    This is where things get interesting. The better you define the problem or the goal/feature you need to implement, and why you need to do it, the easier all the following steps will be. So this is something worth investing in even before you start writing your RFC - make sure you talk to all the involved parties (e.g., product owner, other developers, and even users) to refine your understanding of the issue you’re about to tackle.

    By doing this, you will also very likely get first hints and pointers on the possible solutions, and develop a rough sense of the problem space you’re in.

    RFC problem definition

    Here are a few tips from the example above:

    • Start with a high-level summary - that way, readers can quickly decide if this is relevant to them or not and whether they should keep reading.
    • Provide some context - Explain a bit about the current state of the world, as it is right now. This can be a single sentence or a whole chapter, depending on the intended audience.
    • Clearly state the problem/goal - explain why there is a problem and connect it with the user’s/company’s pain, so that motivation is clear.
    • Provide extra details if possible - diagrams, code examples, … → anything that can help the reader get faster to that “aha” moment. Extra points for using collapsible sections, so the central part of the RFC remains of digestible length.

    If you did all this, you’re already well on your way to the excellent RFC! Since defining the problem well is essential, don’t be afraid to add more to it and break things down further.

    Non-goals 🛑​

    This is the sub-section of the "Problem" or "Goal" section that can sometimes be super valuable. Writing what we don't want or will not be doing in this codebase change can help set the expectations and better define its scope.

    For example, if we are working on adding a role-based authentication system to our app, people might assume that we will also build some sort of an admin panel for it to manage users and add/remove roles. By explicitly stating it won't be done (and briefly explaining why - not needed, it would take too long, it will be done in the next iteration, ...), reviewers will get a better understanding of what your goal is and you will skip unnecessary discussion.

    Solution & Implementation 🛠️​

    Once we know what we want to do, we have to figure out the best way of doing it! You might have already hinted at the possible solution in the Problem section, but now is the moment to dive deeper - research different approaches, evaluate their pros and cons, and sketch how they could fit into the existing system.

    This section is probably the most free-form of all - since it highly depends on the nature of what you are doing, it doesn’t make sense to impose many restrictions here. You may want to stay at the higher level of, e.g., system architecture, or you may need to dive deep into the code and start writing parts of the code you will need. Due to that, I don’t have an exact format for you to follow, but rather a set of guidelines:

    Write pseudocode​

    The purpose of RFC is to convey ideas and principles, not production-grade code that compiles and covers all the edge cases. Feel free to invent/imagine/sketch whatever you need (e.g., imagine you already have a function that sends an email and just use it, even if you don’t), and don’t encumber yourself or the reader with the implementation details (unless that’s exactly what the RFC is about).

    It’s better to start at the higher level, and then go deeper when you realize you need it or if one of the reviewers suggests it.

    Find out how are others doing it​

    See what others are doing

    How you find this out may differ depending on the type of product you’re developing, but there is almost always a way to do it. If you’re developing an open-source tool like Wasp you can simply check out other popular solutions (that are also open-source) and learn how they did it. If you’re working on a SaaS and need to figure out whether to use cookies or JWTs for the authentication, you likely have some friends who have done it before, and you can ask them. Lastly, simply Google/GPT it.

    Why is this so helpful? The reason is that it gives you (and the reviewers) confidence in your solution. If somebody else did it successfully this way, it might be a promising direction. It also might help you discover approaches you haven’t thought of before, or serve as a basis on top of which you can build. Of course, never take anything for granted and take into account the specific needs of your situation, but definitely make use of the knowledge and expertise of others.

    Leave things unfinished & don't make it perfect​

    The main point of RFC is the “C” part, so collaboration (yes, I know it actually stands for "comments"). RFC is not a test where you have to get the perfect score and have no questions asked - if that happens, you probably shouldn’t have written it in the first place.

    Solving a problem is a team effort, and you’re just the person taking the first stab at it and pushing things forward. Your task is to lay as much groundwork as you reasonably can (refine the problem, explore multiple approaches to solving it, identify new subproblems that came to light) so the reviewers can quickly grasp the status and provide efficient feedback, directed where it’s needed the most.

    The main job of your RFC is to identify the most important problems and direct the reviewer’s attention to them, not solve them.

    The RFC you’re writing should be looked at as a discussion area and a work-in-progress, not a piece of art that has to be perfected before it’s displayed in front of the audience.

    Remarks & open questions 🎯​

    In this final section of the document, you can summarise the main thoughts and highlight the biggest open questions. After going through everything, it can be helpful for the reader to be reminded of where his attention can be most valuable.

    Now I know when and how to write an RFC! Do you have any templates I could use as a starting point?​

    Of course! As mentioned, our format is extremely lightweight, but feel free to take a look at the RFC we used as an example to get inspired. Your company could also already have a ready template they recommend.

    Here are a few you can use and/or adapt to your needs:

    What tool should I use to write my RFCs? There are so many choices!​

    The exact tool you’re using is probably the least important part of RFC-ing, but it still matters since it sets the workflow around it. If your company has already selected a tool, then of course stick with that. If not, here are the most common choices I’ve come across, along with quick comments:

    • Google Docs - the classic choice. Super easy to comment on any part of the doc, which is the most important feature.
    • Notion - also great for collaboration, plus offers some markdown components such as collapsibles and tables, which can make your RFC more readable.
    • GitHub issues / PRs - this is sometimes used, especially for OSS projects. The drawback is that it is harder to comment on the specific part of the document (you can only comment on the whole line), plus inserting diagrams is also quite clunky. The pro is that everything (code and RFCs) stays on the same platform

    We currently use Notion, but any of the above can be a good choice.

    Summary​

    Just as it is the best practice to write a summary at the end of your RFC, we will do the same here! This article came out longer than I expected, but there were so many things to mention - I hope you'll find it useful!

    Finally, being able to clearly express your thoughts, formulate the problem, and objectively analyze the possible solutions, with feedback from the team, is what will help you develop the right thing, which is the ultimate productivity hack. This is how you become a 10x engineer.

    And don't forget: Weeks of coding can save you hours of planning.

    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/2024/01/23/wasp-launch-week-five.html b/blog/2024/01/23/wasp-launch-week-five.html index 14ef925628..b13743077a 100644 --- a/blog/2024/01/23/wasp-launch-week-five.html +++ b/blog/2024/01/23/wasp-launch-week-five.html @@ -18,14 +18,14 @@ - - - + + +

    Wasp Launch Week #5: Waspnado 🐝 🌪️

    · 5 min read
    Matija Sosic

    Launch Week 5 is here

    New Year, New Wasp! That's we at first wanted to use as motto for this launch, but then I bought a DALL-E subscription and typed in "Waspnado, but with plushies". The rest is history.

    TL;DR - Wasp is getting dangerously close to 10,000 stars on GitHub and our Discord community is shy of 2,000 members! We're seeing more and more users building and deploying cool apps, both AI-powered, but also good old SaaS-es. Another thing we still have to get used to is getting nice messages from you, such as this one:

    Nice testimonial

    Thank you! This means a lot to us and reassures our that we are on the right path. Now, without the further ado, let's dive in and see what awaits us this week (a tornado of new features, of course):

    Day 1: Wasp Auth 2.0​

    Auth is one Wasp's flagship, and most popular features. All you need to do is add providers you want to use in Wasp config file (e.g. email, Google, or GitHub) and poof - Wasp will magically create a full-stack auth for you, from the database models to the UI components that you can simply import and use. Here's an 1-minute tour:

    And the best part - this all works without any 3rd party services! This is all your code that runs on your infrastructure, and you don't have to pay for it, no matter how many users you have. Pretty neat, huh?

    This is all old news, so what's new? I won't spoil too much, but we might have made it even easier to use (no more manually defining data models), plus it now might use a popular library that starts with "L" (and ends with "ucia") under the hood. I won't say anything more!

    Read more about it:

    Day 2: Wasp, restructured - package.json is back! 🏗️​

    Pinocchio
    Yes, Wasp, you are a real framework now!

    This is a big one, and the most complex feature we'll be shipping this week! We've been designing Wasp from day 1 to work nicely with other pieces of the stack, such as React and Node.js. But, some decisions we made in the process on how all these work together weren't the most elegant, both for you as users and us as developers of the framework.

    With these changes, Wasp will feel much more like a "real" framework that you are used to - you will be able to use npm install, access your package.json, tsconfig, and more!

    Day 3: Wasp AI aka MAGE now lives in your CLI! 🤖 📟​

    MAGE is an AI-powered, full-stack, React and Node.js web app generator powered by Wasp. All it takes is writing a short description and that's it - you will get a complete codebase you can download, run locally, adjust to your wishes and deploy!

    It is one of our most successful products that has been used to kickstart over 30,000 applications!

    MAGE in action - browser

    So far, you could access MAGE only through it's web interface, hosted at https://usemage.ai/. This is super handy to get started quickly, but what if you already have Wasp installed on your computer, or you want more control over the generation (e.g. use GPT-4 exclusively)? That's when running MAGE from you CLI comes into play! Here's how it works:

    This is also the foundation for adding more advanced features to MAGE in the future, like interactive debugging.

    Day 4: Open SaaS - freedom to the boilerplate!​

    Open SaaS revolution

    Remember seeing the boilerplate starters costing more than $300, just to start your side project, and then you still have to maintain all that code? Well, we do, and we say no more!

    All the best things in the world are free, and there aren't much better things than a feature-rich, production-grade boilerplate starter for React & Node.js with admin dashboard, Stripe and OpenAI integration and more - 100% free and open source! (love is a close second)

    You can check it out at https://opensaas.sh/ and give it a star on https://github.com/wasp-lang/open-saas - more details coming soon!

    Day 5 - New Year, New Wasp!​

    Say my name

    On the last day of the Launch Week, we're not presenting another feature, but rather a new brand for Wasp (don't worry, Da Boi stays). It will be shorter, sleeker and even easier to remember. Stay tuned and see what this is all about!

    Stay in the loop​

    dont leave

    Every day, we'll update this page with the latest announcement of the day - to stay in the loop, follow us on Twitter/X and join our Discord - see you there!

    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/2024/01/30/open-saas-free-open-source-starter-react-nodejs.html b/blog/2024/01/30/open-saas-free-open-source-starter-react-nodejs.html index 5792bb2dfd..9119ee0d66 100644 --- a/blog/2024/01/30/open-saas-free-open-source-starter-react-nodejs.html +++ b/blog/2024/01/30/open-saas-free-open-source-starter-react-nodejs.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ Image description Client-side types will be inferred correctly! Image description

    AI-powered Example App (w/ OpenAI API)​

    Image description

    AI is making new app ideas possible, which is partly why we’re seeing a resurgence in developer interest in creating SaaS apps. As I mentioned above, the first SaaS app I built, CoverLetterGPT, is one of those “GPT Wrappers”, and I’m proud to say it makes a nice passive income of ~$350 MRR (monthly recurring revenue).

    I personally believe we’re in a sweet spot in software development where there exists a lot of potential to develop new, profitable AI-powered apps, especially by "indiehackers" and "solopreneurs".

    This is why Open SaaS features an AI scheduling assistant demo app. You input your tasks for along with their alotted time, and the AI Scheduler creates a detailed plan for your day.

    Image description

    Under the hood, this is using OpenAI’s API to assign each task a priority, and break them up into detailed sub-tasks, including coffee breaks! It’s also leverages OpenAI’s function calling feature to return the response back in a user-defined JSON object, so that the client can consume it correctly every time. Also, we're planning on adding open-source LLMs in the future, so stay tuned!

    The demo AI Scheduler is there to help developers learn how to use the OpenAI API effectively, and to spark some creative SaaS app ideas!

    Deploy Anywhere. Easily.​

    A lot of the popular SaaS starters out there use hosting-dependent frameworks, which means you're stuck relying on one provider for deployments. While these can be easy options, it may not always be the best for your app.

    Wasp gives you endless possibilities for deploying your full-stack app:

    • One-command deploy to Fly.io with wasp deploy
    • Use wasp build and deploy the Dockerfiles and client wherever you like!

    The great thing about wasp deploy, is that it automatically generates and deploys your database, server, and client, as well as sets up your environment variables for you.

    Open SaaS also has built in environment variable and constants validators to make sure that you’ve got everything correctly set up for deployment, as well as deployment guides in the docs

    Image description

    In the end, you own your code and are free to deploy it wherever, without vendor lock-in.

    Help us, help you​

    Open SaaS - Open-source & 100% free React & Node.js SaaS starter! | Product Hunt

    Wanna support our free, open-source initiative? Then go show us some support on Product Hunt right now! 🙏

    Image description

    Now Go Build your SaaS!​

    We hope that Open SaaS empowers more developers to ship their ideas and side-projects. And we also hope to get some feedback and input from developers so we can make this the best SaaS boilerplate starter out there.

    So, please, if you have any comments or catch any bugs, submit an issue here.

    And if you’re finding Open SaaS and/or Wasp useful, the easiest way to support is by throwing us a star:

    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/2024/04/25/first-framework-that-lets-you-visualize-react-node-app-code.html b/blog/2024/04/25/first-framework-that-lets-you-visualize-react-node-app-code.html index f4dfd29b9e..4b4607a539 100644 --- a/blog/2024/04/25/first-framework-that-lets-you-visualize-react-node-app-code.html +++ b/blog/2024/04/25/first-framework-that-lets-you-visualize-react-node-app-code.html @@ -18,14 +18,14 @@ - - - + + +

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

    · 9 min read
    Vinny

    Wasp Studio screenshot, baby sleep tracker

    Visualize the Prize​

    Imagine you’re working on your full-stack app, and you want to implement a new feature. It’s a complicated one, so you whip out a pen and paper, or head over to tldraw, and start drawing a diagram of what your app currently looks like, from database, to server, and on over to the client.

    But how cool would it be if you had a tool that visualized your entire full-stack app for you? And what if that tool had the potential to do greater things, like instantly add useful functionality for you across your entire stack, or be paired with AI and Large Language Models for code generation?

    Well, that idea is already a reality, and it’s called wasp studio. Check it out here:

    Wasp Studio is the Name​

    First off, Wasp is a full-stack React, NodeJS, and Prisma framework with superpowers. It just crossed 10,000 stars on GitHub, and it has been used to create over 50,000 projects.

    Why is it special? It uses a config file and its own compiler to manage a bunch of features for you, like auth, cron jobs, routes, and email sending, saving you tons of time and letting you focus on the fun stuff.

    Wasp how-it-works diagram

    This combination of Wasp’s central config file, which acts as a set of instructions for the app, and compiler also allow Wasp to do a bunch of complex and interesting tasks for you via one-line commands, such as:

    • full-stack deployments → wasp deploy
    • starting a development database with Docker → wasp start db
    • scaffold entire example apps, such as a SaaS starter → wasp new
    • giving you a visual schematic of your entire full-stack app → wasp studio

    If you wanna try them out yourself all you have to do is:

    1. install Wasp with curl -sSL https://get.wasp-lang.dev/installer.sh | sh
    2. scaffold a new To Do app in TypeScript with wasp new -t todo-ts
    3. then to get the visualizer as in the screenshot below, run wasp studio

    Baby Sleep Tracker in Wasp Studio

    Let’s break down what we’re seeing here real quick:

    • Our main App component in the middle in blue shows the app’s name, database we’re using, and its Auth method
    • Entities to the left in yellow show us which database models we’ve defined
    • Actions and Queries to the far left in red and green show us our server operations that act on our database entities
    • Routes and Pages on the right show us where our React components live and if they require authorization or not (denoted by 🔒)

    And if you’re wondering what this might look like with a more complex app, here’s what it looks like when run against Open SaaS - our free, open-source SaaS boilerplate starter.

    Open SaaS in Wasp Studio

    What’s great about this is that we have an overview of all our database entities and which server functions (aka “operations”) they depend on. In the top left of the picture above, you’ll even see a cron job, dailyStatsJob, which runs every hour (0 * * * *).

    This, for example, makes developing backend logic a breeze, especially if you’re not a seasoned backend developer. Consider that the code that gets you there is as simple as this:

    job dailyStatsJob {
      executor: PgBoss,
      perform: {
        fn: import { calculateDailyStats } from "@src/calculateDailyStats"
      },
      schedule: {
        cron: "0 * * * *" 
      },
      entities: [User, DailyStats, Logs, PageViewSource]
    }

    Yep, that’s all it takes for you to get asynchronous jobs on your server. Now your calculateDailyStats function will run every hour — no third party services needed 🙂

    Is this a Party Trick!?​

    Ok. You might be thinking, the visualizer is cool, but does it actually serve a purpose or is it just a nice “party trick”? And to be honest, for now it is a party trick.

    But it’s a party trick with a lot of potential up its sleeve. Let me explain.

    You got potential, kid.

    Of course, you can use it in its current form to get a better perspective of your app, or maybe plan some new features, but in the future you will be able to use it to do a lot more, such as:

    • add new auth methods with a few clicks
    • quickly scaffold functional client-side components with server operations
    • instantly add new full-stack functionality to your entire app, like Stripe payments
    • collaborate easily with Large Language Models (LLMs) to generate features on-the-fly!

    Again, this is all possible because of the central configuration file which acts as a set of “instructions” for your app. With this file Wasp literally knows how your app is built, so it can easily display your app to you in visual form. It also makes it a lot easier to build new parts of your app for you in exciting new ways.

    Take a look at another snippet from a Wasp config file below. This is all it takes to get full-stack auth for your web app! That’s because the Wasp compiler is managing that boilerplate code for you.

    app todoVisualize {
      title: "todo-visualize",

      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {}, 
          google: {},
        },
      }
    }

    entity User {=psl
      id          Int     @id @default(autoincrement())
      tasks       Task[]
    psl=}

    A Picture is Worth a Thousand Tokens

    Now that we know a bit about how Wasp works, let’s dive deeper into the potential of Wasp and wasp studio in combination with LLMs as a future use case.

    Currently one of the biggest constraints to AI-assisted code generation is context. By now, we all know that LLMs like to hallucinate, but they also have a pretty bad “memory”. So, if you were to try and get them to build features for your app, to make sure that the new feature works with it, you have to constantly “remind” them of how the app works, its structure, and dependencies.

    But with Wasp’s config file, which is essentially just a higher-level abstraction of a full-stack app and its features, we give the LLM the context it needs to successfully build new features for the app at hand.

    PG tweet

    And this works really well because we don’t only give the LLM the context it needs, but Wasp’s compiler also takes on the responsibility of writing most of the boilerplate for us to begin with (thanks, pal), giving the LLM the simpler tasks of writing, e.g.:

    • modifications to the Wasp config file
    • functions to be run on the server
    • React components that use Wasp code

    In this sense, the LLM has to hold a lot less in context and can be forgiven for its bad memory, because Wasp is the one making sure everything stays nicely glued together!

    To further bring the point home, let’s take a look again at that Auth code that we introduced above:

    auth: {
      userEntity: User,
      methods: {
        usernameAndPassword: {}, 
        google: {},
      },

    Consider that this code gives auth across your entire stack. So, not only do you get all the auth logic generated and managed for you on the server, but you even get UI components and auth hooks made available to you on the client!

    Wasp Auth UI

    On the other hand, without the abstractions that Wasp gives us, we end up relying on the LLM, with it’s bad memory and tendency to hallucinate, to write a bunch of boilerplate for us over and over again like this JWT middleware pictured below:

    Auth without Wasp

    And LLMs are pretty good at coding boilerplatey, repetitive tasks in isolation. But expecting them to do it as part of a cohesive full-stack app means that we have a ton more surface area for exposure to possible errors.

    With Wasp, on the other hand, it’s just a few lines of code. If it’s easy for humans to write, it’s also super easy for an LLM to write.

    By the way, not only does this save us a lot of headache, it also can save us a lot of money too, as AI-generated Wasp apps use ~10-40x less tokens (i.e. input and output text) than comparable tools, so they generate code at a fraction of the price.

    Helping the Computers Help Us​

    As technologies continue to improve, programming will become more accessible to users with less expert knowledge because more of that expert knowledge will be embedded in our tools.

    But that means we will need abstractions that allow for us, the humans, to work easily with these tools.

    Like the LLM example above, we can build tools that get AIs to write all the boilerplate for us over and over again, but the question is, should we be letting them do that when they could be doing other more useful things? LLMs are great at producing a wealth of new ideas quickly. Why not build tools that let AIs help us in this regard?

    That’s exactly what we have planned for the future of wasp studio. A visual interface that allows you to piece together new features of your app, with or without the help of LLMs, and then A/B test those different ideas quickly.

    Not only that, but we also then have an abstraction at our disposal that allows for easy collaboration with users who are less technically inclined. With the help of such tools, even your Product Manager could get in on the fun and start building new features for the developers to sign off on.

    What’s so powerful about Wasp and its feature set, is that we get code that’s simpler to read, debug, and maintain, for both people and machines. Coupled with a visual interface, we will be able to quickly iterate on new features across the entire stack, using it as a planning and orchestration tool ourselves, or as a way to more easily debug and oversee the work an LLM might be doing for us.

    This is a pretty exciting look at the future of web development and with these new tools will come lots of new ways to utilize them.

    What are some ways that you think a tool like wasp studio could be used? What other developments in the realm of AI x Human collaboration can you imagine are coming soon?

    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/2024/05/22/how-to-get-a-web-dev-job-2024.html b/blog/2024/05/22/how-to-get-a-web-dev-job-2024.html index fd622ffb09..657b32def1 100644 --- a/blog/2024/05/22/how-to-get-a-web-dev-job-2024.html +++ b/blog/2024/05/22/how-to-get-a-web-dev-job-2024.html @@ -18,14 +18,14 @@ - - - + + +

    How to get a Web Dev Job in 2024

    · 12 min read
    Vinny

    Hey, I'm Vince...​

    https://dev-to-uploads.s3.amazonaws.com/uploads/articles/az8xf61b2qxx1msfo4t5.png

    I’m a self-taught developer that changed careers during the Covid pandemic. I was able to switch from education to web development by learning and building in my free time, participating in hackathons, and creating educational content for devs.

    Back when I was finding my first dev job, although I was determined to become a staff engineer, I started out by taking a very low-paying “traineeship” position. Although it wasn’t ideal, it allowed me to learn on-the-job and get my foot in the door.

    A year later, and after a lot of hard work, I got offered a much better position and 3x’ed my previous salary! 🤯

    https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sf1fhsgwuurkre9a7drq.png

    Today, I’m currently working as the founding Developer Relations Engineer for Wasp where I build things like OpenSaaS.sh, a free, open-source SaaS starter template for React and NodeJS, along with Stripe, OpenAI, and AWS S3 integration. It’s based on what I learned from building my first profitable SaaS app, CoverLetterGPT.xyz, which currently has over 100 customers and makes ~$500 per month! Nothing crazy, but something I’m still proud of.

    And now that I’m currently in a developer-facing role, I often get asked by people in our community for tips on landing jobs in tech. With this in mind, and with these past experiences under my belt, I thought I’d write a comprehensive article that shares what I’ve learned and seen to be the most effective ways to do so.

    Enjoy!

    Current Job Market for Developers in 2024​

    First of all, let’s take a quick look at the current job market for software developers.

    Image description

    If you spend time on Reddit or X.com (aka Twitter), then you’ve probably seen people complaining about how crappy the current job market is for developers.

    To try and find some actual statistics to back up these claims, I used Perplexity.ai to help me find some information on the current demand for software developers, and I was surprised at the results.

    Apparently, the demand for software developers remains high, in fact the demand is higher than other jobs, on average, and is expected to grow even more in the coming years!

    So why does it feel even harder than usual for some developers to land a job at the moment?

    Well, that’s because it actually is harder, but only if you’re a less-experienced developer.

    On the other hand, If you’re an experienced dev with a strong portfolio of work, there are a lot more open roles out there for you. But if you’re a junior developer just starting out, the competition is fiercer than ever.

    And there are few reasons for that:

    1. Complexity of Skills Required: software development is increasingly complex and requires a broad set of skills, making it difficult for many candidates to meet job requirements.
    2. Remote Work Trends: The shift to remote work has disrupted the entry-level developer pipeline, making it harder for companies to find and train new talent.
    3. Economic Factors: The pandemic and subsequent economic shifts have led to fluctuating hiring patterns, with some periods of high layoffs followed by surges in demand.

    Basically, even though there is high demand for experienced developers, there is a comparatively low demand for the less experienced ones.

    So with this relatively large supply of beginner and mid-level engineers all competing to get the same jobs, how can you gain the skills of an experienced dev and make yourself stand out from the crowd?

    Be a problem solver, not just a coder​

    A career in software development means that change is a constant. You always have to be ready to learn new things and go outside of your comfort zone because,

    1. the job demands it, and
    2. the industry evolves at an extremely fast pace

    In such an environment certificates, courses, and degrees (to a certain extent) matter less, because they don’t prove you have the skill needed to adapt to and solve new problems as they arise. Sure, they prove that you have a certain amount of fundamental knowledge, but that’s only a fraction of the necessary skills needed for the job.

    You want to be able to show that you can tackle a challenge that you’ve never faced before, by:

    • quickly learning about this new topic,
    • finding a suitable approach to solving it, and
    • executing on that approach quickly in order to realize your goal

    Image description

    But don’t just take it from me. AJ, aka Techfren on TikTok, talks about how to navigate the current job environment in a post-AI world. He makes a couple good points that are related to this article here. For example:

    1. General coding knowledge is even less relevant because AI possesses a really broad range of coding knowledge. As an engineer, you’re no longer valuable because you know how to code — an AI now knows how to code pretty damn well (and in a lot more programming languages than you). Your value comes in thinking critically, solving problems, and architecting solutions to those problems.
    2. Businesses will start looking more for these generalist problem solvers to build in-house apps (i.e. internal tools) as replacements to paid services in order to save money and meet their specific business demands, since AI allows developers to be way more productive.

    So it’s obvious that problem-solving skills are in high demand, and will continue to be even more important in the future. And we can assume that more experienced, in-demand developers possess those skills, so how do we build them ourselves?

    Solve your own Problems​

    Ok. So you consider yourself to be a curious developer, that can adapt and learn new things quickly, and solve problems on the fly.

    But how do you prove this to prospective employers?

    Easy. Just solve your own problems! In practice — and in the realm of web development — this means “being on the edge of your comfort zone” and building a web app that’s unique to you and your interests.

    Image description

    Cameron Blackwood, a self-taught engineer and content creator, describes this perfectly in his TikTok video advising new developers on how to improve their skills. He also has a unique perspective because he previously worked as a tech recruiter, and he says:

    • Build a web app that solves a problem you have in your everyday life
    • Try different things than you’re currently learning / doing at your day job.
    • Keep building and trying new things in your free time.

    Of course, these apps you make don’t have to be perfect, but the more unique they are, and the more they show a creative and well-realized solution to a problem, the better.

    And if you’re having trouble thinking of things to build, sometimes just experimenting with new tools can inspire new ideas. But however you decide to approach it is up to you, the important thing is to start, so get cracking!

    By the way, Wasp is a great way to easily build new apps that solve your unique problems. It’s also one of the quickest ways to build bespoke full-stack apps in React & NodeJS without having to write a bunch of boilerplate code for things like auth, routes, end-to-end typesafety, deployments and more.

    As an example, check out this video below which shows you how easy it is to implement full-stack authentication across your entire app.

    Do the grunt work​

    ok

    As I was writing this article, I was lucky enough to come across this tweet from Jonathan Stern where he talks about advice he found extremely valuable when he started his first dev job.

    Before that job, Jonathan wrote an email to Replit's CEO, Amjad Masad and asked for advice when starting his first job as a software developer.

    Here's what Amjad said:

    Two ways to prove yourself and make yourself indispensable:

    1. be incredibly productive and inventive -- which is really hard to do when you're starting out

    2. do the boring work that no one wants to do

    #2 is available for everyone, it just requires effort and discipline but no one does it, so I would suggest doing that. Incidentally, #2 can often lead to #1 in interesting ways.

    Now, even though this is advice for developers who already have a job, I think it is advice that a lot of less experienced devs also looking for jobs should hear.

    Amjad’s advice in a broader sense is to basically lower your expectations at first and work hard. Doing the boring work that no one wants to do also might mean doing work that you’re not keen on, but it will benefit you in the long run.

    This could also mean taking on jobs that aren’t exactly what you wished for earlier on, and doing the grunt work, in order to become that “indispensable” developer that any employer would love to have on their team.

    Be a Good Person​

    This advice is very general, and can apply to just about any job (or anything), but being a good person to work with is probably a lot more valuable and overlooked than most job seekers imagine.

    Once you’ve met the job requirements, a lot of what makes you attractive to prospective employers is whether they could imagine working in a team with you or not. And while that may seem simple and straightforward from the outside, it’s actually a lot harder to put into practice.

    Image description

    Think about it.

    You’ll be working on a team with lots of different personalities. Tasks can get complex, deadlines get tight, and the work can get messy. Mistakes will be definitely be made.

    Are you the type of person to lose their sense of humor under pressure?

    How will you react when someone blames you for a mistake you weren’t directly responsible for?

    Do you communicate openly and effectively with your team?

    Will you stay humble and conscientious after 1 year of hard work with no raise? Will you stay humble and conscientious after 1 year of hard work, lots of praise, and a sweet raise (this is probably even harder)?

    Being a honest, open, and genuine are valuable traits that are hard to come by, and people can often tell in an instant if you’re that type of person or not. And it’s these type of people, when put up against other candidates that also meet the job requirements, that ultimately end up getting the job offer.

    More Effort into Less Applications​

    One of the things that I and a lot of other employers complain about is when job applicants put little to no effort into their applications. The worst offense is when the application is obviously just a copy-and-paste effort.

    typing

    Employers hate this because it’s an obvious sign of how you will work on the job. If your job application is done lazily, then it’s very likely your work on the job will be performed similarly (or worse!).

    That’s why I think it’s best to put more of your effort into fewer job applications.

    There is no magic number, but whenever I was applying to jobs there were always 2 or 3 that I was really excited about. So those were the only ones I applied to, and I put a lot of thought and effort into these applications.

    Image description

    Besides making my own portfolio with descriptions and learning objectives for my projects, I would also create some form of extra content that was related to the job application. In some instances, this was a simple example app, or in others an explainer video or article.

    What was important was that these extra pieces of content were attempts at solving the problems or tasks presented in the job description, to show that I can do that type of work well, and that I’m eager and willing to do the grunt work.

    My assumption was that most other applicants wouldn’t go to these lengths when applying and therefore my application would stand out from the crowd, and it worked well as I got asked to interview for many of those positions even without a lot of prior experience!

    Now Get That Job…​

    The software developer job market is changing. It makes sense because the role of the software developer is also constantly evolving, and now that we’re entering the era of AI, these roles are evolving at an even faster pace.

    This means, as employers adapt, they’ll probably continue to look for the developers that can prove they’re able to keep up with all these developments, and utilize the tools at hand to solve problems faced in the world around us.

    So if you’re able to prove this, while being a conscientious and humble worker, than you probably won’t have such a hard time finding that sweet tech job you’ve always wanted. It’s just a matter of putting in the focus and energy on the right things now, which at times may be hard, that will make the process of finding a job later a whole lot easier.

    Thanks for reading and happy job hunting.

    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/2024/05/29/why-we-dont-have-laravel-for-javascript-yet.html b/blog/2024/05/29/why-we-dont-have-laravel-for-javascript-yet.html index 76f6ed4771..978291ccf7 100644 --- a/blog/2024/05/29/why-we-dont-have-laravel-for-javascript-yet.html +++ b/blog/2024/05/29/why-we-dont-have-laravel-for-javascript-yet.html @@ -18,14 +18,14 @@ - - - + + +

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

    · 12 min read
    Vinny

    JavaScript's Need for a Full-stack Framework​

    “Why Don't We Have A Laravel For JavaScript?”. This is the question Theo poses in his most recent video.

    And if you’re not familiar with tools like Laravel and Ruby-on-Rails, they are opinionated full-stack frameworks (for PHP and Ruby) with lots of built-in features that follow established conventions so that developers can write less boilerplate and more business logic, while getting the industry best practices baked into their app.

    Image description

    He answers this question with the opinion that JavaScript doesn’t need such frameworks because it’s better to select the tools you want and build the solution you need yourself.

    This sounds great — and it also happens to be a nice flex if you’re a seasoned dev — but I feel that he doesn’t back up this claim very well, and I’m here to tell you where I think he’s wrong.

    In my opinion, the better question to ask is why don’t we have a Laravel for JavaScript yet? The answer being that we’re still working on it.

    In his summary of the full-stack frameworks of the JavaScript world that could be comparable to Laravel or Rails, he fails to consider a few important points:

    1. People really want a Laravel / Rails for JavaScript. If they didn’t, there wouldn’t be so many attempts to create one, and he wouldn’t be making a video whose sole purpose is to respond to the pleading cry “WHY DOESN’T JAVASCRIPT HAVE ITS OWN LARAVEL!?”
    2. He fails to consider the timing and maturity of the underlying tools within the JS ecosystem. Perhaps it’s not that a Laravel for JavaScript doesn’t need to exist, it’s just that it doesn’t exist yet due to some major differences in the ecosystems themselves, like how old they are and where the innovation is mostly happening.
    3. He also fails to ask for whom these types of solutions are suitable for. Surely, not all devs have the same objectives, so some might opt for the composable approach while others prefer to reach for a framework.

    So let’s take a look at how we got to the point we’re at today, and how we might be able to bring a full-stack framework like Laravel or Rails to the world of JavaScript.

    Getting Shit Done​

    In his video, Theo brings up the point that "there's a common saying in the React world now which is that ‘if you're not using a framework you're building one’”. Even though this is meant to be used as a criticism, Theo feels that most JavaScript devs are missing the point and that building your “own framework” is actually an advantage.

    Image description

    He feels that the modular nature of the JavaScript ecosystem is a huge advantage, but that sounds like a lot of pressure on the average developer to make unnecessary judgement calls and manage lots of boilerplate code.

    Sure, you have teams that need to innovate and meet the needs of special use cases. These are the ones that prioritize modularity. They tweak, improve, and squeeze as much out of developer experience (DX) and performance as possible to get their unique job done right.

    But on the other hand, there are also numerous teams whose main objective is producing value and innovating on the side of the product they are building, instead of the tools they are using to build it. These devs will favor a framework that allows them to focus solely on the business logic. This gives them a stable way to build stuff with best practices so they can easily advance from one project to another. In this camp are also the lean, mean indiehackers looking for frameworks so they can move fast and get ideas to market!

    Image description

    It’s a bit like the difference between Mac and Linux. Mac’s unified stack that just works out-of-the box means many professionals prefer it for its productivity, whereas Linux is great if you’re looking for flexibility and have the time and knowledge to tweak it to your desires. Both are valid solutions that can coexist to meet different needs.

    This focus on productivity is what made Rails so powerful back in the day, and why Laravel is such a loved framework at the moment. And the many attempts at creating such a framework for JavaScript is proof enough that there is a large subset of JavaScript devs who also want such a solution.

    But maybe the reason such a framework doesn’t exist yet doesn’t have to do with whether devs want one or not, but rather the important factors which are needed in order for such a framework to come together haven’t aligned up until this point. For such a framework to be widely adoptable, it first needs underlying technologies that are stable enough to build upon. After that, it needs time and many iteration cycles to reach maturity itself, so that devs can feel comfortable adopting it.

    Have these factors aligned in the JavaScript world to give us the type of frameworks that PHP and Ruby already have? Maybe not quite yet, but they do seem to be slowly coming together.

    Comparing Ecosystems​

    One of Theo’s main points is that JavaScript as a language enables a level of modularity and composability that languages like Ruby and PHP don’t, which is why Ruby and PHP ecosystems are well served by full-stack frameworks, but JavaScript doesn’t need one since you can just compose stuff on your own.

    While JavaScript is a peculiar language, with its support for both functional and imperative paradigms and dynamic nature, it also comes with a lot of pitfalls (although it has improved quite a bit lately), so you don’t typically hear it get praised in the way Theo does here. In fact, you are probably more likely to hear praise for Ruby and its properties as a modular and flexible language.

    So if it isn’t some unique properties of JavaScript as a language that make it the king of web dev, what is it then?

    Image description

    Well, the answer is pretty simple: JavaScript is the language of the browser.

    Way back when most of the web development was happening on the server side, PHP, Java, Ruby and other languages where reigning supreme. During this era, devs would only write small pieces of functionality in JavaScript, because most of the work was being handled server-side.

    But as web development evolved and we started building richer applications, with more dynamic, responsive, and real-time features, a lot of code moved away from the server and over towards JavaScript on the client, because it’s (basically) the only language that supports this. So instead of doing your development mostly in PHP or Ruby with a little bit of JavaScript sprinkled in there, you were now splitting your apps between substantial amounts of JavaScript on the client, plus Ruby or PHP on the server.

    JavaScript’s final power move came with the arrival of NodeJS and the ability to also write it on the server, which secured its position as the king of web dev languages. Today, devs can (and do) write their entire apps in JavaScript. This means you need to know one language less, while you’re also able to share the code between front-end and back-end. This has opened up a way for better integration between front-end and back-end, which has snowballed into the ecosystem we know today.

    So it’s not so much the unique properties of JavaScript as a language that have made it the dominant ecosystem for web development, but more its unique monopoly as the only language that can be used to write client code, plus it can also be used server-side.

    Image description

    As Theo says, “we’ve got infinitely more people making awesome solutions” in the JavaScript ecosystem. That’s right. It’s exactly those infinite number of developers working in the space creating the flexibility and modular solutions for JavaScript, rather than it being an innate quality of the programming language.

    And because the JavaScript ecosystem is still the hottest one around, it has the most devs in total while continuing to attract new ones every day. This means that we get a large, diverse community doing two main things:

    1. Innovating
    2. Building

    The innovators (and influencers) tend to be the loudest, and as a result opinion largely skews in their favor. But there is also a lot of building, or “normal” usage, happening! It’s just that the innovators tend to do the talking on behalf of the builders.

    So with all that’s going on in the JavaScript ecosystem, is it pointless to try and build a lasting framework for JavaScript developers, as Theo suggests, or are we on the path towards achieving this goal regardless of what the innovators might claim?

    Show Me What You’re Working With​

    Theo also drops the names of a bunch of current JavaScript frameworks that have either failed to take off, or “just can’t seem to get it right” when it comes to being a comprehensive full-stack solution.

    Image description

    And he does have a point here. So far, solutions like Blitz, Redwood, Adonis, or T3 haven’t managed to secure the popularity in their ecosystem that Rails or Laravel have in theirs.

    But these things take time.

    Have a look at the graph above. Laravel and Rails have been around for 13-15 years! The JavaScript frameworks being used in comparison are just getting started, with some of them, like Wasp and Redwood, at similar stages in their development as Laravel and Rails were during their initial years.

    As you can see, it takes time for good solutions to reach maturity. And even with some of these frameworks starting to stagnate their great initial growth is evidence that demand for these tools definitely exists!

    The main overlying issue that tends to plague these tools is that Javascript as an ecosystem is moving quite fast, so for a solution like this to survive long term, it needs to not only be opinionated enough, but also modular enough to keep up with the shifts in the ecosystem.

    Image description

    One factor that prevents frameworks from reaching this state is being tied too tightly to the wrong technology. This was NextJS for BlitzJS, GraphQL for Redwood, and Blaze for MeteorJS. And another factor is not going big enough with the framework, because it seems too daunting a task within the JavaScript ecosystem, where things move fast and everyone is “terrified of being opinionated” because they might get criticized by the loudest voices in the scene.

    In other words, frameworks that avoid going big on their own, and going truly full-stack, like Ruby-on-Rails and Laravel went, miss the opportunity to solve the most common pain-points that continue to plague JavaScript developers.

    But, the JavaScript ecosystem is maturing and stabilizing, we are learning from previous attempts, and there will be a full-stack framework bold enough to go all the way in, get enough things right, and persist for long enough to secure its place.

    Say Hi to Wasp​

    In his comparison of JavaScript frameworks on the market today, Theo also fails to mention the full-stack framework for React & NodeJS that we’re currently working on, Wasp.

    We’ve been working hard on Wasp to be the truly full-stack framework that meets the demands of web developers and fills that void in the JavaScript ecosystem to become the framework they love to use.

    Image description

    With Wasp, we decided to go big, opinionated, and truly full-stack. In other words, we’re going all in with this framework.

    That means thinking from first principles and designing a novel approach that only Wasp uses, like building our own compiler for our configuration language, and truly going full-stack, while also keeping it modular enough to move together with the ecosystem as it progresses.

    This means that we spent more time in the beginning trying different approaches and building the foundation, which finally brought us a significant jump in usage starting in late 2023. Wasp is now growing strong, and at a really fast pace!

    It’s really cool for us to see Wasp being used today to ship tons of new apps and businesses, and even being used internally by some big names and organizations (more info on that will be officially released soon)!

    Image description

    What Wasp does differently than other full-stack frameworks in the JavaScript world is that it separates it’s main layer of abstraction into its own configuration file, main.wasp. This config file gives Wasp the knowledge it needs to take care of a lot of the boilerplatey, infrastructure-focused code, and allows it to have this unique initial compile-time step where it is able to reason about your web app before it generates the code for it in the background (using that knowledge while generating it).

    In practice, this means that all you have to do is describe your Wasp app at a high level in Wasp’s config file, and then implement everything else in technologies that you’re familiar with such as React, NodeJS, and Prisma. It also means that Wasp has a high modularity potential, meaning we are building it to also support other frontend frameworks in the future, like Vue, Solid or Svelte, and to even support additional back-end languages, like Python, Go or Rust.

    If you’re the kind of developer that wishes a Rails or Laravel for JavaScript existed, then you should give Wasp a try (and then head into our Discord and let us know what you think)!

    Where Are We Headed?​

    We firmly believe that there will be a full-stack framework for JavaScript as there is Laravel for PHP and Ruby-on-Rails for Ruby.

    It just seems like, at the moment, that we’re still working towards it. It also seems very likely that we will get there soon, given the popularity of current meta-frameworks and stacks like NextJS and T3.

    But this stuff takes time, and patience.

    Plus, you have to be bold enough to try something new, knowing you will get criticized for your work by some of the loudest voices in the ecosystem.

    That’s what we’re prepared for and why we’re going all in with Wasp.

    See you there!

    Image description

    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/2024/07/03/building-selling-saas-in-5-months.html b/blog/2024/07/03/building-selling-saas-in-5-months.html index cdf36a210d..5f3cd59f67 100644 --- a/blog/2024/07/03/building-selling-saas-in-5-months.html +++ b/blog/2024/07/03/building-selling-saas-in-5-months.html @@ -18,14 +18,14 @@ - - - + + +

    Building and Selling a GPT Wrapper SaaS in 5 Months

    · 7 min read
    Vinny

    Since the release of ChatGPT, we’ve been flooded with all possible versions of apps that use it in one way or another. Building on top of trendy technology is an excellent way to get initial attention, but still, 99% of these apps die very quickly and don’t last beyond a week or two following their “big” Twitter or Product Hunt launch.

    Why? Because they aren’t solving a real problem. It’s either a fun tech gadget or a gross overpromise (e.g., “you will never need to code again,” which I strongly disagree with) that quickly falls short.

    Building a successful product still follows the same rules as in the pre-GPT era: find a problem people are willing to pay for and then figure out a way to reach these people. Sounds simple? It is, but it for sure isn’t easy. The good news is that GPT opened so many new opportunities that actually doing it is faster and easier than ever.

    Meet the hero of our story - Max! 🦸​

    our-hero-max

    The hero of our story today is Max, a software engineer at Red Hat. He built https://description-generator.online (an AI description generator for Etsy products) and sold it on acquire.com. A senior backend engineer by day and a serial hacker and tinkerer by night, Max always had a passion for building products, and GPT was the last piece of the puzzle he was waiting for.

    Read on to learn how he went through the entire cycle of finding a problem, building a solution, getting customers, and ultimately selling his app in 5 months total.

    Lesson #1: Look for problems in “unusual” places 🕵️‍♂️​

    Looking for problems

    TL;DR: Talk to your friends who aren’t developers! Learn about their problems and offer help. The more unfamiliar and disconnected from tech their occupation is, the better - these are gold mines for GPT-powered solutions!

    It all started with Max’s friend who owns an Etsy marketplace - she needed help with some data/workflow automation, and Max agreed to lend a hand. Consequently, he also started hanging out in the Ukranian Etsy community on Slack.

    Soon, he learned that one of the most common requests there is for help with writing product descriptions (”listings”) in English. Although most members used English daily and had no problem communicating, writing high-quality, compelling, and professional-sounding listings was still a challenge. Auto-translation services still weren’t sophisticated enough, and hiring native English speakers was too expensive for most.

    This sounded like a real, glaring problem directly connected to the number of items Etsy sellers sell and, thus, the profit they make. As it turned out, it was the case.

    Lesson #2: Build a prototype, fast 🏎️​

    Image description

    TL;DR: Speed is the name of the game here. Don’t spend time flexing on your stack and optimizing to the last byte. Pick something that works and ship it!

    The problem of writing convincing product listings in English caught Max’s attention. He was aware of ChatGPT and how useful it could be for this. However, being a backend engineer with limited frontend experience, building a full-stack app around it and choosing and configuring all parts of the stack himself sounded daunting and laborious. It wasn’t until he came across Open SaaS that he felt ready to take action.

    The prototype was ready after a couple of days, and Max immediately shared it with his Etsy community. He kept it extremely simple - no landing page or any copy at all (just a form to enter your product details), even no custom domain yet, but myProduct.fly.io you get assigned upon deploying to Fly (which takes just a single CLI command with Wasp).

    And that was enough - as his product scratched the itch Etsy sellers repeatedly mentioned, the reception was overwhelmingly positive! In just a few days, Max got 400 signups, and several hundred product listings were generated daily.

    By the way, if you’re looking for an easy, low maintenance way to start your next side project, check out Open SaaS, a 100% free, open-source Saas Starter!

    https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sf1fhsgwuurkre9a7drq.png

    Open SaaS is a feature-rich, React + NodeJS SaaS template, with Stripe, OpenAI / GPT app examples, AWS S3 file upload, Analytics, Admin Dashboard, and full Documentation!

    Lesson #3: Test willingness to pay early 💸​

    money please

    TL;DR: People signing up for your product is amazing, but convincing them to pay is a completely separate game. If you want to ensure your solution brings real value and you’re not wasting time, find a way to test monetizing as early as possible.

    Max saw the adoption picking up, which made him ask himself “How do I turn this into a business? What would users be willing to pay for?” After all, he had his own expenses, like server costs and GPT API subscription.

    Looking at how users use the product, he quickly realized he could make generating descriptions even easier - a seller could upload the image of a product, and that’s it; the full product description can be generated directly from it. That was a good candidate for a “premium” feature, since it was an upgrade on top of the basic functionality.

    Max added the feature, and soon enough, the first customers started rolling in! 💰

    Lesson #4: Keep building or sell? How to decide 🤔​

    homer selling

    TL;DR: Is the market’s domain something you’re personally excited about and see yourself in for the long term? Do you feel your competitive advantage will grow stronger with time? If yes, keep building. Otherwise, sell!

    description-generator.online now had both users and first revenue, amazing! Still, soon, it became apparent that the Etsy community Max was part of had its limits. Although all non-English speaking markets shared the problem, which made for a big opportunity, reaching them and setting up and executing a sales process would still take time and effort.

    On the other hand, competing products started appearing. Although super valuable for Etsy sellers, if Max built the product in a week, others could do it too. It started becoming clear that the value of the business would soon start moving from the technical solution to sales, support, and customer experience.

    Being a hacker at heart and not so personally invested in arts & crafts marketplaces, Max decided to sell the product to somebody who is. He listed the description generator on https://acquire.com/, along with the usage metrics and relevant data, and soon started receiving offers.

    Lesson #5: Provide support during acquisition 🤝​

    got my back

    TL;DR: Selling your product takes more than finding a buyer. Providing impeccable support during acquisition is just as important as building the product.

    Finding a buyer and agreeing on a price took about a month. Since the buyer was taking over everything - the source code, domain, and customers, Max providing 3-month support with the transition was an essential part of the deal.

    Also, since they couldn’t use an escrow service due to some technical and geographical limitations, they agreed on splitting the payment 50/50 - half in the beginning and another half when the migration was over. Max made sure his customers had a flawless experience with moving everything over, resulting in a great relationship mutually filled with trust. Besides selling your app, making friends is an underrated bonus! 😎

    After a few months, the deal has been reached! Description-generator.online got a new owner, an expert in the industry willing to expand to new markets, and Max got his first exit and could move on to the next exciting project!

    Summary​

    michael summary

    That’s it! Building a product others find helpful so much they’re willing to pay for it is a deeply gratifying experience. We saw how Max did it and what lessons he learned along the way:

    1. Look for problems in “unusual” places
    2. Build a prototype fast
    3. Test willingness to pay early
    4. Decide whether you want to keep building or sell
    5. Provide support during the acquisition

    Hopefully, this was helpful!

    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/2024/07/15/wasp-launch-week-six.html b/blog/2024/07/15/wasp-launch-week-six.html index a98c28c185..0fdc3f320b 100644 --- a/blog/2024/07/15/wasp-launch-week-six.html +++ b/blog/2024/07/15/wasp-launch-week-six.html @@ -18,14 +18,14 @@ - - - + + +

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

    · 5 min read
    Matija Sosic

    Launch Week 6 is here

    Bonjour Wasp connoisseurs 🐝 👋,

    It's been a while, but we're back! We've been busy wasps and put our antennae down to work to deliver you v0.14, which is happening in exactly two days, on July 17th!

    It's happening!

    To reserve your spot (we can fit only so many people in our Discord), click here.

    Join the kick-off event

    Once you see the invite, mark yourself as "Interested," and that's it (don't make us talk to ourselves again)! Also, if you thought you'd slip by without a bad joke, you were direly wrong:

    Why do wasps never leave tips? Because they are stingy.

    🤯🤯🤯

    Okay, now to the fun stuff—let's see what we're packing into this upcoming release!

    #1: 📝 Define your data models in a separate prisma.schema file!​

    This change marks the beginning of one of our most requested features - splitting your Wasp config into multiple files! We know that as you develop your Wasp app and it grows, it can become unwieldy to have everything in one hefty .wasp file.

    Define data models in prisma.schema file

    That's why we started by extracting the data model definitions into a standalone Prisma schema file! This will significantly reduce the size of the Wasp config file and also allow for a more streamlined experience of writing PSL (Prisma Schema Language), with all the goodies like syntax highlighting and auto-completion working out of the box 🎉.

    #2: 🔒 Auth Hooks - onBeforeSignup, onAfterSignup, and more!​

    Auth lifecycle hooks

    Although Wasp's Auth feature is probably the fastest way to get authentication running in your full-stack app, adding your custom logic to the auth process can also be quite handy—e.g. if you want to log something, do some extra config etc.

    We've made that easy, by offering several authentication lifecycle hooks that you can use for the exact purpose!

    #3: 🆕 New authentication provider: Discord!​

    Discord as a new auth provider

    This one is pretty self-explanatory, but that doesn't make it any less cool! Besides Google and GitHub, Discord is now a third social auth method natively supported by Wasp, next to Google and GitHub - that means all you need to do is define a single line in your Wasp config, and voilà - your users can now sign in with Discord!

    #4: 👀 TypeScript SDK RFC - a sneak peek!​

    TS SDK proposal of code

    As you might have seen in the community, this has been an ongoing topic of discussion for a while. Although having a dedicated configuration language (DSL) allows for the maximum customizability of the DX, having Wasp config in TypeScript instead will help out with language tooling (IDE syntax highlighting and auto-completion). Also, it might feel even more familiar to developers using Wasp.

    This is why we decided to test the waters and see how we (and you) like it! We are still working out what it will look like, and we have laid out some of the ideas in this RFC for TS SDK. We'd love to hear from you and get your comments and ideas in this GitHub issue (or just come to our Discord and bash us there 😅)

    #5: 🤯 OpenSaaS, Reloaded!​

    Open SaaS banner

    And finally, the star of the last launch week, Open SaaS, a 100% free and open-source boilerplate starter for React & Node.js, powered by Wasp, has received its first makeover! You gave us a ton of amazing feedback and ideas, and we listened. Here's what's new:

    • Simplified Stripe payment logic
    • The code is now organized vertically by features (instead of client and server folders)
    • Introduced e2e tests with Playwright
    • Added an optional cookie consent banner that hooks up to Google Analytics
    • Bunch of small bug fixes and docs updates

    And more! Don't forget that Lambo you will earn with your SaaS is just within arm's reach (well, it depends on how long your arm is). All you have to do is go to OpenSaaS and finally start that app you've been dreaming about 🏎️.

    #6: 🫵 See you there!​

    That's pretty much it—we've given you a taste of what's coming, but for the real deal, you'll have to join us on Wednesday! Register here and make sure to mark yourself as interested—we'll see you there if you don't see us first (sorry)!

    Join the kick-off event

    Register for the kick-off event here.

    Stay in the loop​

    dont leave

    Every day, we'll update this page with the latest announcement of the day - to stay in the loop, follow us on Twitter/X and join our Discord - see you there!

    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/2024/08/13/how-to-add-auth-with-lucia-to-your-react-nextjs-app.html b/blog/2024/08/13/how-to-add-auth-with-lucia-to-your-react-nextjs-app.html index 606a5e1a2c..43f6c5835e 100644 --- a/blog/2024/08/13/how-to-add-auth-with-lucia-to-your-react-nextjs-app.html +++ b/blog/2024/08/13/how-to-add-auth-with-lucia-to-your-react-nextjs-app.html @@ -18,15 +18,15 @@ - - - + + +

    How to Add Auth with Lucia to Your React/Next.js App - A Step by Step Guide

    · 15 min read
    Lucas Lima do Nascimento

    How to Add Auth to Your App

    Although authentication is one of the most common web app features, there are so many different ways to go about it, which makes it a very non-trivial task. In this post, I will share my personal experience using Lucia - a modern, framework-agnostic authentication library that has been getting, deservedly so, a lot of love from the community in recent months.

    First, I will demonstrate how you can implement it within your Next.js application through a step-by-step guide you can follow. It will require a fair amount of code and configuration, but the process itself is quite straightforward.

    Secondly, we’ll see how to achieve the same with Wasp in just a few lines of code. Wasp is a batteries-included, full-stack framework for React & Node.js that uses Lucia under the hood to implement authentication. It runs fully on your infrastructure and is 100% open-source and free.

    auth with Wasp

    Why Lucia?​

    When it comes to adding authentication to your applications, there are several popular solutions available. For instance, Clerk offers a paid service, while NextAuth.js is an open-source solution alongside Lucia, which has become quite popular recently.

    These tools provide robust features, but committing to third-party services — which not only adds another layer of complexity but also have paid tiers you have to keep an eye on — might be an overkill for a small project. In-house solutions keep things centralized but leave it to a developer to implement some of the mentioned features.

    In our case, Lucia has proved to be a perfect middle ground - it’s not a third-party service and does not require a dedicated infrastructure, but it also provides a very solid foundation that’s easy to build upon.

    Now, let’s dive into a step-by-step guide on how to implement your own authentication with Next.js and Lucia.

    Step 1: Setting up Next.js​

    First, create a new Next.js project:

    npx create-next-app@latest my-nextjs-app
    cd my-nextjs-app
    npm install

    Step 2: Install Lucia​

    Next, install Lucia:

    npm install lucia

    Step 3: Set up Authentication​

    Create an auth file in your project and add the necessary files for Lucia to be imported and initialized. It has a bunch of adapters for different databases, and you can check them all here. In this example, we’re going to use SQLite:

    // lib/auth.ts
    import { Lucia } from "lucia";
    import { BetterSqlite3Adapter } from "@lucia-auth/adapter-sqlite";

    const adapter = new BetterSQLite3Adapter(db); // your adapter

    export const lucia = new Lucia(adapter, {
      sessionCookie: {
        // this sets cookies with super long expiration
        // since Next.js doesn't allow Lucia to extend cookie expiration when rendering pages
        expires: false,
        attributes: {
          // set to `true` when using HTTPS
          secure: process.env.NODE_ENV === "production"
        }
      }
    });

    // To get some good Typescript support, add this!
    declare module "lucia" {
      interface Register {
        Lucia: typeof lucia;
      }
    }

    Step 4: Add User to DB​

    Let’s add a database file to contain our schemas for now:

    lib/db.ts
    import sqlite from "better-sqlite3";

    export const db = sqlite("main.db");

    db.exec(`CREATE TABLE IF NOT EXISTS user (
        id TEXT NOT NULL PRIMARY KEY,
        github_id INTEGER UNIQUE,
        username TEXT NOT NULL
    )`);

    db.exec(`CREATE TABLE IF NOT EXISTS session (
        id TEXT NOT NULL PRIMARY KEY,
        expires_at INTEGER NOT NULL,
        user_id TEXT NOT NULL,
        FOREIGN KEY (user_id) REFERENCES user(id)
    )`);

    export interface DatabaseUser {
      id: string;
      username: string;
      github_id: number;
    }

    Step 5: Implement Login and Signup​

    To make this happen, we firstly have to create a GitHub OAuth app. This is relatively simple, you create it, add the necessary ENVs and callback URLs into your application and you’re good to go. You can follow GitHub docs to check how to do that.

    .env.local
    GITHUB_CLIENT_ID=your-github-client-id
    GITHUB_CLIENT_SECRET=your-github-client-secret

    After that, it’s a matter of adding login and signup functionalities to your pages, so, let’s do that real quick:

    login/page.tsx
    import { validateRequest } from "@/lib/auth";
    import { redirect } from "next/navigation";

    export default async function Page() {
      const { user } = await validateRequest();
      if (user) {
        return redirect("/");
      }
      return (
        <>
          <h1>Sign in</h1>
          <a href="/login/github">Sign in with GitHub</a>
        </>
      );
    }

    After adding the page, we also have to add the login redirect to GitHub and the callback that’s going to be called. Let’s first add the login redirect with the authorization URL:

    login/github/route.ts
    import { generateState } from "arctic";
    import { github } from "../../../lib/auth";
    import { cookies } from "next/headers";

    export async function GET(): Promise<Response> {
      const state = generateState();
      const url = await github.createAuthorizationURL(state);

      cookies().set("github_oauth_state", state, {
        path: "/",
        secure: process.env.NODE_ENV === "production",
        httpOnly: true,
        maxAge: 60 * 10,
        sameSite: "lax"
      });

      return Response.redirect(url);
    }

    And finally, the callback (which is what we actually add in GitHub OAuth):

    login/github/callback/route.ts
    import { github, lucia } from "@/lib/auth";
    import { db } from "@/lib/db";
    import { cookies } from "next/headers";
    import { OAuth2RequestError } from "arctic";
    import { generateId } from "lucia";

    import type { DatabaseUser } from "@/lib/db";

    export async function GET(request: Request): Promise<Response> {
      const url = new URL(request.url);
      const code = url.searchParams.get("code");
      const state = url.searchParams.get("state");
      const storedState = cookies().get("github_oauth_state")?.value ?? null;
      if (!code || !state || !storedState || state !== storedState) {
        return new Response(null, {
          status: 400
        });
      }

      try {
        const tokens = await github.validateAuthorizationCode(code);
        const githubUserResponse = await fetch("https://api.github.com/user", {
          headers: {
            Authorization: `Bearer ${tokens.accessToken}`
          }
        });
        const githubUser: GitHubUser = await githubUserResponse.json();
        const existingUser = db.prepare("SELECT * FROM user WHERE github_id = ?").get(githubUser.id) as
          | DatabaseUser
          | undefined;

        if (existingUser) {
          const session = await lucia.createSession(existingUser.id, {});
          const sessionCookie = lucia.createSessionCookie(session.id);
          cookies().set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
          return new Response(null, {
            status: 302,
            headers: {
              Location: "/"
            }
          });
        }

        const userId = generateId(15);
        db.prepare("INSERT INTO user (id, github_id, username) VALUES (?, ?, ?)").run(
          userId,
          githubUser.id,
          githubUser.login
        );
        const session = await lucia.createSession(userId, {});
        const sessionCookie = lucia.createSessionCookie(session.id);
        cookies().set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
        return new Response(null, {
          status: 302,
          headers: {
            Location: "/"
          }
        });
      } catch (e) {
        if (e instanceof OAuth2RequestError && e.message === "bad_verification_code") {
          // invalid code
          return new Response(null, {
            status: 400
          });
        }
        return new Response(null, {
          status: 500
        });
      }
    }

    interface GitHubUser {
      id: string;
      login: string;
    }

    Other important thing here is that, now, we’re going with GitHub OAuth, but, generally, these libraries contain a bunch of different login providers (including simple username and password), so it’s usually just a pick and choose if you want to add other providers.

    lib/auth.ts
    import { Lucia } from "lucia";
    import { BetterSqlite3Adapter } from "@lucia-auth/adapter-sqlite";
    import { db } from "./db";
    import { cookies } from "next/headers";
    import { cache } from "react";
    import { GitHub } from "arctic";

    import type { Session, User } from "lucia";
    import type { DatabaseUser } from "./db";

    // these two lines here might be important if you have node.js 18 or lower. 
    // you can check Lucia's documentation in more detail if that's the case 
    // (https://lucia-auth.com/getting-started/nextjs-app#polyfill)
    // import { webcrypto } from "crypto";
    // globalThis.crypto = webcrypto as Crypto;

    const adapter = new BetterSqlite3Adapter(db, {
      user: "user",
      session: "session"
    });

    export const lucia = new Lucia(adapter, {
      sessionCookie: {
        attributes: {
          secure: process.env.NODE_ENV === "production"
        }
      },
      getUserAttributes: (attributes) => {
        return {
          githubId: attributes.github_id,
          username: attributes.username
        };
      }
    });

    declare module "lucia" {
      interface Register {
        Lucia: typeof lucia;
        DatabaseUserAttributes: Omit<DatabaseUser, "id">;
      }
    }

    export const validateRequest = cache(
      async (): Promise<{ user: User; session: Session } | { user: null; session: null }> => {
        const sessionId = cookies().get(lucia.sessionCookieName)?.value ?? null;
        if (!sessionId) {
          return {
            user: null,
            session: null
          };
        }

        const result = await lucia.validateSession(sessionId);
        // next.js throws when you attempt to set cookie when rendering page
        try {
          if (result.session && result.session.fresh) {
            const sessionCookie = lucia.createSessionCookie(result.session.id);
            cookies().set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
          }
          if (!result.session) {
            const sessionCookie = lucia.createBlankSessionCookie();
            cookies().set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
          }
        } catch {}
        return result;
      }
    );

    export const github = new GitHub(process.env.GITHUB_CLIENT_ID!, process.env.GITHUB_CLIENT_SECRET!);

    Step 6: Protect Routes​

    After adding all that stuff to make the login properly work, we just have to ensure that routes are protected by checking authentication status — in this case, this is a simple page that shows username, id and a button in case signed in, and redirects to /login, where the user will complete the login above through a form.

    profile/page.tsx
    import { lucia, validateRequest } from "@/lib/auth";
    import { redirect } from "next/navigation";
    import { cookies } from "next/headers";

    export default async function Page() {
      const { user } = await validateRequest();
      if (!user) {
        return redirect("/login");
      }
      return (
        <>
          <h1>Hi, {user.username}!</h1>
          <p>Your user ID is {user.id}.</p>
          <form action={logout}>
            <button>Sign out</button>
          </form>
        </>
      );
    }

    async function logout(): Promise<ActionResult> {
      "use server";
      const { session } = await validateRequest();
      if (!session) {
        return {
          error: "Unauthorized"
        };
      }

      await lucia.invalidateSession(session.id);

      const sessionCookie = lucia.createBlankSessionCookie();
      cookies().set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
      return redirect("/login");
    }

    interface ActionResult {
      error: string | null;
    }

    Piece of cake, isn’t it? Well, not really.

    Let’s recap which steps were necessary to actually make this happen:

    • Set up your app.
    • Add Lucia.
    • Set up authentication.
    • Add User to DB.
    • Obtain GitHub OAuth credentials and configure your environment variables.
    • Create some util functions.
    • Add Login and Sign up routes, with custom made components.
    • Finally, create a protected route.

    https://media2.giphy.com/media/3ofSBnYbEPePeigIMg/giphy.gif?cid=7941fdc6x77sivlvr6hs2yu5aztvwjvhgugv6b718mjanr2h&ep=v1_gifs_search&rid=giphy.gif&ct=g

    Honestly, when trying to create something cool FAST, repeating these steps and debugging a few logical problems here and there that always occur can feel a little bit frustrating. Soon, we’ll take a look at Wasp’s approach to solving that same problem and we’ll be able to compare how much easier Wasp’s auth implementation process is.

    In case you want to check the whole code for this part, Lucia has an example repo (that is the source of most of the code shown), so, you can check it out if you’d like.

    Wasp Implementation​

    Now, let’s go through how we can achieve the same things with Wasp 🐝. Although it still uses Lucia in the background, Wasp takes care of all the heavy-lifting for you, making the process much quicker and simpler. Let’s check out the developer experience for ourselves.

    Before we just into it, in case you’re more of a visual learner, here’s a 1-minute video showcasing auth with wasp.

    As seen in the video, Wasp is a framework for building apps with the benefits of using a configuration file to make development easier. It handles many repetitive tasks, allowing you to focus on creating unique features. In this tutorial, we’ll also learn more about the Wasp config file and see how it makes setting up authentication simpler.

    Step 1: Create a Wasp Project​

    curl -sSL https://get.wasp-lang.dev/installer.sh | sh
    wasp new my-wasp-app
    cd my-wasp-app

    Step 2: Add the User entity into our DB​

    As simple as defining the app.auth.userEntity entity in the schema.prisma file and running some migrations:

    model User {
      id Int @id @default(autoincrement())
      email   String   @unique
      name    String?
      // Add your own fields below
      // ...
    }

    Step 3: Define Authentication​

    In your main Wasp configuration, add the authentication provider you want for your app

    main.wasp
    app myApp {
      wasp: {
        version: "^0.14.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          // 2. Enable Github Auth
          gitHub: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    And after that, just run in your terminal:

    wasp db migrate-dev

    Step 4: Get your GitHub OAuth credentials and app running​

    This part is similar for both frameworks, you can follow the documentation GitHub provides here to do so: Creating an OAuth app - GitHub Docs. For wasp app, the callback urls are:

    • While developing: http://localhost:3001/auth/github/callback
    • After deploying: https://your-server-url.com/auth/github/callback

    After that, get your secrets and add it to the env file:

    .env.server
    GITHUB_CLIENT_ID=your-github-client-id
    GITHUB_CLIENT_SECRET=your-github-client-secret

    Step 5: Add the routes and pages​

    Now, let’s simply add some routing and the page necessary for login — the process is way easier since Wasp has pre-built Login and Signup Forms, we can simply add those directly:

    main.wasp
    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage"
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage"
    }
    src/LoginPage.jsx
    import { Link } from 'react-router-dom'
    import { LoginForm } from 'wasp/client/auth'

    export const LoginPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <LoginForm />
          <br />
          <span>
            I don't have an account yet (<Link to="/signup">go to signup</Link>).
          </span>
        </div>
      )
    }
    src/SignupPage.jsx
    import { Link } from 'react-router-dom'
    import { SignupForm } from 'wasp/client/auth'

    export const SignupPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <SignupForm />
          <br />
          <span>
            I already have an account (<Link to="/login">go to login</Link>).
          </span>
        </div>
      )
    }

    And finally, for protecting routes, is as simple as changing it in main.wasp adding authRequired: true , so, we can simply add it like this:

    main.wasp
    page MainPage {
      component: import Main from "@src/pages/Main",
      authRequired: true
    }

    If you’d like to check this example in more depth, feel free to check this repo here: wasp/examples/todo-typescript at release · wasp-lang/wasp (github.com). Other great place to check is their documentation, which can be found here. It covers most of what I said here, and even more (e.g. the awesome new hooks that came with Wasp v0.14)

    https://media4.giphy.com/media/nDSlfqf0gn5g4/giphy.gif?cid=7941fdc6oxsddr7p8rjsuavcyq7ugiad8iqdu1ei25urcge4&ep=v1_gifs_search&rid=giphy.gif&ct=g

    Way easier, isn’t it? Let’s review the steps we took to get here:

    • Set up the project.
    • Add the User entity to the database.
    • Define authentication in the main Wasp configuration.
    • Obtain GitHub OAuth credentials and configure your environment variables.
    • Add routes and pages for login and signup with pre-built, easy-to-use components.
    • Protect routes by specifying authRequired in your configuration.

    Customizing Wasp Auth​

    If you need more control and customization over the authentication flow, Wasp provides Auth hooks that allow you to tailor the experience to your app's specific needs. These hooks enable you to execute custom code during various stages of the authentication process, ensuring that you can implement any required custom behavior.

    For more detailed information on using Auth hooks with Wasp, visit the Wasp documentation.

    Bonus Section: Adding Email/Password Login with Wasp and Customizing Auth​

    Now let’s imagine we want to add email and password authentication — with all the usual features we’d expect that would follow this login method (e.g. reset password, email verification, etc.).

    With Wasp, all we have to do is add a few lines to your main.wasp file, so, simply updating your Wasp configuration to include email/password authentication makes it work straight out of the box!

    https://wasp-lang.dev/img/auth-ui/auth-demo-compiler.gif

    Wasp will handle the rest, also updating UI components and ensuring a smooth and secure authentication flow.

    main.wasp
    app myApp {
      wasp: {
        version: "^0.14.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the User entity
        userEntity: User,
        methods: {
          // 2. Enable Github Auth
          gitHub: {},
          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
            emailVerification: {
              clientRoute: EmailVerificationRoute, //this route/page should be created
            },
            passwordReset: {
              clientRoute: PasswordResetRoute, //this route/page should be created
            },
            // Add an emailSender -- Dummy just logs to console for dev purposes
            // but there are a ton of supported providers :D
            emailSender: {
              provider: Dummy,
            },
          },
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    Implementing this in Next.js with Lucia would take a lot more work, involving a bunch of different stuff from actually sending the emails, to generating the verification tokens and more. They reference this here, but again, Wasp’s Auth makes the whole process way easier, handling a bunch of the complexity for us while also giving a bunch of other UI components, ready to use, to ease the UI details (e.g. VerifyEmailForm, ForgotPasswordForm and, ResetPasswordForm).

    The whole point here is the difference in time and developer experience in order to implement the same scenarios. For the Next.js project with Lucia, you will spend at least a few hours implementing everything if you’re going all by yourself. That same experience translates to no more than 1 hour with Wasp. What to do with the rest of the time? Implement the important stuff your particular business requires!

    Can you show us your support?​

    https://media2.giphy.com/media/l0MYAs5E2oIDCq9So/giphy.gif?cid=7941fdc6l6i66eq1dc7i5rz05nkl4mgjltyv206syb0o304g&ep=v1_gifs_search&rid=giphy.gif&ct=g

    Are you interested in more content like this? Sign up for our newsletter and give us a star on GitHub! We need your support to keep pushing our projects forward 😀

    Conclusion​

    https://media2.giphy.com/media/l1AsKaVNyNXHKUkUw/giphy.gif?cid=7941fdc6u6vp4j2gpjfuizupxlvfdzskl03ncci2e7jq17zr&ep=v1_gifs_search&rid=giphy.gif&ct=g

    I think that if you’re a developer who wants to get things done, you probably noted the significant difference in complexity levels of both of those implementations.

    By reducing boilerplate and abstracting repetitive tasks, Wasp allows developers to focus more on building unique features rather than getting bogged down by authentication details. This can be especially beneficial for small teams or individual developers aiming to launch products quickly.

    Of course, generally when we talk abstractions, it always comes with the downside of losing the finesse of a more personal implementation. In this case, Wasp provides a bunch of stuff for you to implement around and uses Lucia on the background, so the scenario where there’s a mismatch of content implementation is highly unlikable to happen.

    In summary, while implementing your own authentication with Next.js and Lucia provides complete control and customization, it can be complex and time-consuming. On the other hand, using a solution like Wasp simplifies the process, reduces code length, and speeds up development.

    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/2024/08/20/django-vs-wasp.html b/blog/2024/08/20/django-vs-wasp.html index 7810310d9a..b552b24790 100644 --- a/blog/2024/08/20/django-vs-wasp.html +++ b/blog/2024/08/20/django-vs-wasp.html @@ -18,14 +18,14 @@ - - - + + +

    Wasp: The JavaScript Answer to Django for Web Development

    · 18 min read
    Sam Jakshtis

    a django dev tries wasp

    Wasp vs Django: Building a full stack application just got a lot easier​

    Hey, I’m Sam, a backend engineer with a lot of experience with Django. I wanted to make the jump and learn some frontend for a full stack app. I quickly experienced the arduous nature of a React-with-Django project and thought the pain was just part of the development process. However, I came across a very cool new full stack framework called Wasp.

    Wasp is an amazing dev tool for full stack applications. Combining things like React, Node.js and Prisma, Wasp allows for development to be expedited in ways never before seen.

    In this article, I am going to walk through creating a full stack application in Django versus Wasp to prove the simplicity of Wasp against a very conventional full-stack technology. I am also going to make a React frontend connected to Django. The point is to highlight the inefficiencies, difficulties, and issues that can (and will) arise with Django/React that are made vastly simpler when working with Wasp.

    This article is not intended as a how-to, but I do provide code snippets to give you a feel for their differences. Also note that in order to give a side-by-side comparison, I'll use tabs which you can switch back and forth between, like this:

    Django info will go here...

    Let's get started

    Part 1: Let There Be Light!​

    Let’s create some projects and set things up​

    This part is about the only part where there is significant overlap between Django and Wasp. Both starting from the terminal, let’s make a simple task app (I am assuming you have Django and Wasp installed and in your path).

    terminal
    django-admin startproject
    python manage.py starapp Todo

    Now Wasp starts hot out of the gate. After running wasp new you'll see a menu, as shown below. Wasp can either start a basic app for you, or you can select from a multitude of pre-made templates (including a fully functioning SaaS app) or even use an AI-generated app based on your description!

    wasp cli menu

    Meanwhile, Django works as a project with apps within the project (again, this is essentially all for backend operations) and there can be many apps to one Django project. Thus, you have to register each app in the Django project settings.

    terminal
    python `manage.py` startapp todo
    settings.py
    INSTALLED_APPS [
    ...
    'Todo'
    ]

    Database Time​

    So now we need a database, and this is another area where Wasp really shines. With Django, we need to create a model in the models.py file. Wasp, meanwhile, uses Prisma as it's ORM which allows us to clearly define necessary fields and make database creation simple in an easy to understand way.

    models.py
    from django.db import models

    class Task(models.Model):
        title = models.CharField(max_length=200)
        completed = models.BooleanField(default=False)

        def __str__(self):
            return self.title

    Django and Wasp do share similar ways to migrate databases:

    python manage.py makemigrations
    python manage.py migrate

    But with Wasp, you can also do some pretty nifty database stuff that Django can't.

    Right now we're using SQLite, but how about instantly setting up a development Posgres database? Wasp can do that with:

    wasp db start

    That's it! With that you've got a docker container running a Postgres instance and it's instantly connected to your Wasp app. 🤯

    Or what if you want to see your database in real time via Prisma’s database studio UI, something not possible without third party extensions with Django. For that, just run:

    wasp db studio

    Are you starting to see what I mean now?

    Routes​

    Routes in Django and Wasp follow a shomewhat similar pattern. However, if you're familiar with React, then Wasp’s system is far superior.

    • Django works through the backend (views.py, which I will get to later in this article) which do all the CRUD operations. Those view functions are associated to a specific route within an app within a project (I know, a lot), and it can get more complicated if you start using primary keys and IDs. You need to create a urls.py file and direct your specific views file and functions to a route. Those app urls are then connected to the project urls. Phew.
    • Wasp’s way: define a route and direct it to a component.
    todo/urls.py
    from django.urls import path
    from . import views

    urlpatterns = [
        path('', views.index, name='index'),
        path('update/<str:pk>/', views.updateTask, name='update_task'),
        path('delete/<str:pk>/', views.deleteTask, name='delete_task'),
    ./urls.py
    from django.contrib import admin
    from django.urls import path, include

    urlpatterns = [
        path('admin/', admin.site.urls),
        path('', include('todo.urls')),
    ]

    CRUD​

    Ok, this is where the benefits of Wasp are about to become even more apparent.

    Firstly, I am going to revisit the views.py file. This is where magic is going to happen for Django backend. Here is a simple version of what the create, update, and delete functions could look like for our Task/Todo example:

    todo/views.py
    from django.shortcuts import render, redirect
    from .models import Task
    from .forms import TaskForm

    def index(request):
        tasks = Task.objects.all()
        form = TaskForm()
        if request.method == 'POST':
            form = TaskForm(request.POST)
            if form.is_valid():
                form.save()
            return redirect('/')
        context = {'tasks': tasks, 'form': form}
        return render(request, 'todo/index.html', context)

    def updateTask(request, pk):
        task = Task.objects.get(id=pk)
        form = TaskForm(instance=task)
        if request.method == 'POST':
            form = TaskForm(request.POST, instance=task)
            if form.is_valid():
                form.save()
            return redirect('/')
        context = {'form': form}
        return render(request, 'todo/update_task.html', context)

    def deleteTask(request, pk):
        task = Task.objects.get(id=pk)
        if request.method == 'POST':
            task.delete()
            return redirect('/')
        context = {'task': task}
        return render(request, 'todo/delete.html', context)
    app/forms.py
    from django import forms
    from .models import Task

    class TaskForm(forms.ModelForm):
        class Meta:
            model = Task
            fields = ['title', 'completed']

    So right now, Wasp has a fully functioning backend with middleware configured for you. At this point we can create some React components, and then import and call these operations from the client. That is not the case with Django, unfortunately there is still a lot we need to do to configure React in our app and get things working together, which we will look at below.

    Part 2: So you want to use React with Django?​

    React with Django is... hard

    At this point we could just create a simple client with HTML and CSS to go with our Django app, but then this wouldn't be a fair comparison, as Wasp is a true full-stack framework and gives you a managed React-NodeJS-Prisma app out-of-the-box. So let's see what we'd have to do to get the same thing set up with Django.

    Note that this section is going to highlight Django, so keep in mind that you can skip all the following steps if you just use Wasp. :)

    Django 🟢

    First thing’s first. Django needs a REST framework and CORS (Cross Origin Resource Sharing):

    terminal
    pip install djangorestframework
    pip install django-cors-headers

    Include Rest Framework and Cors Header as installed apps, CORS headers as middleware, and then also set a local host for the React frontend to be able to communicate with the backend (Django) server (again, there is no need to do any of this initial setup in Wasp as it's all handled for you):

    settings.py
    INSTALLED_APPS = [
        ...
        'corsheaders',
    ]

    MIDDLEWARE = [
        ...
        'corsheaders.middleware.CorsMiddleware',
        ...
    ]

    CORS_ALLOWED_ORIGINS = [
        'http://localhost:3000',
    ]

    And now a very important step, which is to serialize all the data from Django to be able to work in json format for React frontend

    app/serializers.py
    from rest_framework import serializers
    from .models import Task

    class TaskSerializer(serializers.ModelSerializer):
        class Meta:
            model = Task
            fields = '__all__'

    Now, since we are handling CRUD on the React side, we can change the views.py file:

    app/views.py
    from rest_framework import viewsets
    from .models import Task
    from .serializers import TaskSerializer

    class TaskViewSet(viewsets.ModelViewSet):
        queryset = Task.objects.all()
        serializer_class = TaskSerializer

    And now we need to change both app and project URLS since we have a frontend application on a different url than our backend.

    urls.py
    from django.contrib import admin
    from django.urls import path, include

    urlpatterns = [
        path('admin/', admin.site.urls),
        path('api/', include('todo.urls')),  # Add this line
    ]
    todo/urls.py
    from django.urls import path, include
    from rest_framework.routers import DefaultRouter
    from .views import TaskViewSet

    router = DefaultRouter()
    router.register(r'tasks', TaskViewSet)

    urlpatterns = [
        path('', include(router.urls)),
    ]

    By now you should be understanding why I've made the switch to using Wasp when building full-stack apps. Anyways, now we are actually able to make a React component with a Django backend 🙃

    React time​

    Ok, so now we can actually get back to comparing Wasp and Django.

    To start, lets create our React app in our Django project:

    terminal
    npx create-react-app frontend

    Finally, we can make a component in React. A few things:

    • I am using axios in the Django project here. Wasp comes bundled with React-Query (aka Tanstack Query), so the execution of (CRUD) operations is a lot more elegant and powerful.
    • The api call is to my local server, obviously this will change in development.
    • You can make this many different ways, I tried to keep it simple.
    main.jsx
    import React, { useEffect, useState } from 'react';
    import axios from 'axios';

    const TaskList = () => {
      const [tasks, setTasks] = useState([]);
      const [newTask, setNewTask] = useState('');
      const [editingTask, setEditingTask] = useState(null);

      useEffect(() => {
          fetchTasks();
      }, []);

      const fetchTasks = () => {
        axios.get('http://127.0.0.1:8000/api/tasks/')
          .then(response => {
            setTasks(response.data);
          })
          .catch(error => {
            console.error('There was an error fetching the tasks!', error);
          });
      };

      const handleAddTask = () => {
        if (newTask.trim()) {
          axios.post('http://127.0.0.1:8000/api/tasks/', { title: newTask, completed: false })
            .then(() => {
              setNewTask('');
              fetchTasks();
            })
            .catch(error => {
              console.error('There was an error adding the task!', error);
            });
        }
      };

      const handleUpdateTask = (task) => {
        axios.put(`http://127.0.0.1:8000/api/tasks/${task.id}/`, task)
          .then(() => {
            fetchTasks();
            setEditingTask(null);
          })
          .catch(error => {
            console.error('There was an error updating the task!', error);
          });
      };

      const handleDeleteTask = (taskId) => {
        axios.delete(`http://127.0.0.1:8000/api/tasks/${taskId}/`)
          .then(() => {
            fetchTasks();
          })
          .catch(error => {
            console.error('There was an error deleting the task!', error);
          });
      };

      const handleEditTask = (task) => {
        setEditingTask(task);
      };

      const handleChange = (e) => {
        setNewTask(e.target.value);
      };

      const handleEditChange = (e) => {
        setEditingTask({ ...editingTask, title: e.target.value });
      };

      const handleEditCompleteToggle = () => {
        setEditingTask({ ...editingTask, completed: !editingTask.completed });
      };

      return (
        <div>
          <h1>To-Do List</h1>
          <input type="text" value={newTask} onChange={handleChange} placeholder="Add new task" />
          <button onClick={handleAddTask}>Add Task</button>
          <ul>
            {tasks.map(task => (
              <li key={task.id}>
                {editingTask && editingTask.id === task.id ? (
                  <div>
                    <input type="text" value={editingTask.title} onChange={handleEditChange} />
                    <button onClick={() => handleUpdateTask(editingTask)}>Save</button>
                    <button onClick={() => setEditingTask(null)}>Cancel</button>
                    <button onClick={handleEditCompleteToggle}>
                      {editingTask.completed ? 'Mark Incomplete' : 'Mark Complete'}
                    </button>
                  </div>
              ) : (
                <div>
                  {task.title} - {task.completed ? 'Completed' : 'Incomplete'}
                  <button onClick={() => handleEditTask(task)}>Edit</button>
                  <button onClick={() => handleDeleteTask(task.id)}>Delete</button>
                </div>
                )}
              </li>
            ))}
          </ul>
        </div>
      );
    };

    export default TaskList;

    Todo app

    In the Wasp app you can see how much easier it is to call the server-side code via Wasp operations. Plus, Wasp gives you the added benefit of refreshing the client-side cache for the Entity that's referenced in the operation definition (in this case Task). And the cherry on top is how easy it is to pass the authenticated user to the component, something we haven't even touched on in the Django app, and which we will talk about more below.

    Part 3: Auth with Django? No way, José​

    Angry desk flip

    So we already started to get a feel in the above code for how simple it is to pass an authenticated user around in Wasp. But how do we actually go about implementing full-stack Authentication in Wasp and Django.

    This is one of Wasp’s biggest advantages. It couldn't be easier or more intuitive. On the other hand, the Django implementation is so long and complicated I'm not going to even bother showing you the code and I'll just list out the stps instead. Let's also look at Wasp first this time.

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.14.0"
      },

      title: "Todo App",

      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {}
        }
      }

      //...

    That's it!

    mind blown

    And that's all it takes to implement full-stack Auth with Wasp! But that's just one example, you can also add other auth methods easily, like google: {}, gitHub: {} and discord: {} social auth, after configuring the apps and adding your environment variables.

    Wasp allows you to get building without worrying about so many things. I don’t need to worry about password hashing, multiple projects and apps, CORS headers, etc. I just need to add a couple lines of code.

    Wasp just makes sense.

    One Final Thing​

    I just want to highlight one more aspect of Wasp that I really love. In Django, we're completely responsible for dealing with all the boilerplate code when setting up a new app. In other words, we have to set up new apps from scratch every time (even if it's been done before a million times by us and other devs). But with Wasp we can scaffold a new app template in a number of ways to really jump start the development process.

    Let's check out these other ways to get a full-stack app started in Wasp.

    Way #1: Straight Outta Terminal​

    A simple wasp new in the terminal shows numerous starting options and app templates. If I really want to make a todo app for example, well there you have it, option 2.

    Right out of the box you have a to-do application with authentication, CRUD functionality, and some basic styling. All of this is ready to be amended for your specific use case.

    Or what if you want to turn code into money? Well, you can also get a fully functioning SaaS app. Interested in the latest AI offereings? You also have a vector embeddings template, or an AI full-stack app protoyper! 5 options that save you from having to write a ton of boilerplate code.

    wasp cli menu

    Way #2: Mage.ai (Free!)​

    Just throw a name, prompt, and select a few of your desired settings and boom, you get a fully functioning prototype app. From here you can use other other AI tools, like Cursor's AI code editor, to generate new features and help you debug!

    mage

    note

    💡 The Mage functionality is also achievable via the terminal (wasp new -> ai-generated), but you need to provide your own OpenAI api key for it to work.

    Can you show us your support?​

    https://media2.giphy.com/media/l0MYAs5E2oIDCq9So/giphy.gif?cid=7941fdc6l6i66eq1dc7i5rz05nkl4mgjltyv206syb0o304g&ep=v1_gifs_search&rid=giphy.gif&ct=g

    Are you interested in more content like this? Sign up for our newsletter and give us a star on GitHub! We need your support to keep pushing our projects forward 😀

    Conclusion​

    So there you have it. As I said in the beginning, coming from Django I was amazed how easy it was to build full-stack apps with Wasp, which is what inspired me to write this article.

    Hopefully I was able to show you why breaking away from Django in favor of Wasp can be beneficial in time, energy, and emotion.

    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/2024/09/03/OS-builders-interview-with-tim-jones-pgboss.html b/blog/2024/09/03/OS-builders-interview-with-tim-jones-pgboss.html index 76f5108fd6..741de88701 100644 --- a/blog/2024/09/03/OS-builders-interview-with-tim-jones-pgboss.html +++ b/blog/2024/09/03/OS-builders-interview-with-tim-jones-pgboss.html @@ -18,14 +18,14 @@ - - - + + +

    The Faces Behind Open Source Projects: Tim Jones and pg-boss

    · 13 min read
    Milica Maksimović

    wasps interviewing Tim

    We’re launching a new series of posts where we'll sit down with the folks who help us run our projects without expecting anyting in return. Yes, we're talking about open-source maintainers and builders, the people who dedicate their free time to make tech better. This is our way to say "Thank you!" to all of those who help us build and improve Wasp, as well as shape the webdev ecosystem.

    In our first post, we had the chance to chat with Tim, the maintainer of pg-boss, a library that makes managing job queues in PostgreSQL a breeze. We talked about what it’s like to maintain an open-source project, the ups and downs, and why Tim keeps coming back to make pg-boss better. If you’ve ever relied on open-source tools, this series is for you.

    Let's dive in!

    • Please tell us a little bit about yourself. When and how did you get introduced to coding?

    I was first introduced to coding in grade school with Logo in the 80s. I built my first website on GeoCities in 97, then started coding professionally with Visual Basic in MS Access during the Y2K craze. I built my first multi-tenant SaaS app (an extranet) in 2002 before it was cool using Classic ASP. I spent at least a decade in C# coding web apps most of the time before finally settling down in the warm embrace of full stack JavaScript with Node.js for the last 10 years.

    • Could you introduce us to pg-boss? Was there a reason or use case you had for creating it?

    I joined a startup in 2015 and we needed an open source relational database so Mongo would stop ruining our lives. I had heard good things about Postgres, so I was excited to give it a chance. Our product also included Redis, but only for the purpose of hosting a job queue via the Kue package. This seemed excessive to manage another piece of infrastructure for a queue, especially for our low-volume requirements. I hadn’t used Redis before, so I started researching it.

    I learned that Redis is a great choice when you need a fast, in-memory database. However, a job queue is a different use case, where you are guaranteeing to someone: “I promise to do this later”. If your Redis server crashes, you could lose a lot of jobs with the default configuration. Their persistence documentation even states, “if you want a degree of data safety comparable to what PostgreSQL can provide you”, you should use both RDB and AOF configurations. Within AOF, there is an option, “appendfsync always”, but it’s generally discouraged with warnings of poor performance. The recommended configuration is almost always “everysec”, but with the disclaimer, “you may lose 1 second of data if there is a disaster”. These warnings about safety should cause anyone in technical leadership to pause and ask some questions.

    Even now in 2024 Redis seems to be the dominant queue persistence database in OSS, but it wasn’t designed to match the use case of a guaranteed job delivery system. Seeing the growth of open source Postgres-backed queues makes me optimistic that over time more development teams realize this mismatch and we’ll see a decline in popularity of the Redis queue projects. If your product relies on Redis for its queue, I encourage you to review your disaster recovery plans and server configurations. It’s concerning that the popularity of the “just use Redis for your queue” is likely producing a large population of applications vulnerable to losing jobs.

    In 2015, the number 1 hit on Google for “Postgres job queue” was Brandur Leach’s “Postgres Job Queues & Failure By MVCC” blog post. LOL! The Internet replied with “don’t do this”. However, at this same point in time Postgres 9.5 was in beta and about to be released, and lo and behold a new core feature was added called SKIP LOCKED. This looked like a perfect fit, but it was too new for any packages to have this approach. After a successful prototype, I thought it seemed like a good opportunity to try creating the package myself, since I was new to Node and wanted to learn more about it. I started building it on nights and weekends, shipped version 0.0.1 in early 2016 then finally released 1.0 a year later.

    • How do you manage contributions and feature requests?

    The best thing about OSS in my opinion is in its name: “open”. Having the entire world of developers not only use your software, but also be able to read its code and make contributions produces the highest quality code. You will get questions you never thought about, and find bugs you didn’t know existed. In the case of bug fixes, most of the time it’s as simple as making sure said bug has a new unit test then merging a pull request (PR).

    Managing feature requests is not easy, however. If you don’t accept any contributions, it seems to violate the principle of OSS. If you accept every contribution, you risk the project drifting away from its original design or becoming too complicated. The balance between these extremes is evaluating each feature request against what seems to be best aligned with the core purpose of the project. This becomes a non-technical decision sometimes, and may result in a “let’s agree to disagree” outcome. My desire is to try and merge all PRs that arrive, and I really appreciate all the contributors that have sent them. It’s not fun saying “no”, because someone put in the coding effort and they felt strongly enough about it to spend their free time on your project.

    • What are the unexpected challenges of managing a successful open-source project?

    I did not expect how time-consuming managing an open source project would be. This is probably the primary reason projects become abandoned over time if they are supported by only 1 or a few developers. For example, you could have a perfectly functioning code base in Node 0.12, then decide to upgrade to async/await later and have to rewrite everything. The same applies to changing a test suite, assertion package, or even striving to attain 100% code coverage.

    • Using Postgres as a queue solution has become quite popular recently :) What are your thoughts on differences between pg-boss and e.g. pgmq?

    This is encouraging to see. I learned about pgmq from this question. It looks like a great option for a pure SQL implementation as a Postgres extension. I haven’t used it so I won’t be able to offer a detailed comparison, but after a quick review I see it uses SKIP LOCKED and a partitioned job table, which are good baseline scalability requirements. Postgres extension version management is challenging, however, and usually involves database service restarts and downtime.

    • What is the largest scale you’ve seen or heard pg-boss used at? How scalable / how far can you go with running background jobs directly in pg?

    In terms of job storage, we’ve been able to store 2-3 million jobs in v9’s shared job storage and survive, but not really thrive, as database performance starts to degrade. Before v10, in order to mitigate this you have to use configuration settings to move completed jobs into the archive more often.

    Once record counts are under control, in terms of job throughput, the number of concurrent queries to Postgres can be very high, especially when using connection poolers and job batching. I have a speed test in the suite that can both fetch and then complete 10,000 jobs in 0.5 seconds, a metric you would not easily be able to achieve even in some dedicated queuing products. For job creation on the other hand, you have the full power of SQL available in Postgres via INSERT or even COPY.

    [Fun fact!]

    Did you know that Wasp uses pg-boss under the hood? We built Wasp Jobs on top of pg-boss, and here's how we did it.

    • While pg-boss has many production use cases, is there a scenario or limit where teams may need a traditional queue instead?

    Because of the limitations in v9, we use pg-boss and AWS SQS side by side. Some of our queues rely heavily on pg-boss’s rate limiting and uniqueness features. We use SQS for queues that can grow very large quickly. Now that we’ve upgraded to v10, we might consider switching back for cost reasons, since SQS is not cheap at this scale.

    • There is a new version of pg-boss v10, what should people be excited about?

    pg-boss v9 and below uses a shared job table across all queues. Once you run into the storage limitations mentioned earlier, all queues are affected. This is especially problematic since queues were also used internally for maintenance and scheduling. Maintenance controls archival, so if this queue can’t be processed, it prevents pg-boss from auto-recovering from this via the retention policy.

    The design goal in v10 was to mitigate this performance issue first by isolating each queue into a dedicated table via partitioning. If a queue were to become backlogged with millions of jobs, it would affect the performance of that queue only. Then, if needed, you could use the newly added deleteJob() function in your workers, inspired by AWS SQS, to keep the record count as low as possible.

    Another very useful new feature is queue policies. Over the years there were several issues opened around worker concurrency, which added several functions and configuration which made the API more complicated and difficult to understand. For example, there was a function sendSingleton(), which behaved entirely different from a configuration option named enforceSingletonQueueActiveLimit. In v10, these were all removed in favor of queue policies. A couple of examples are “short” queues, which only allow 1 pending job, no matter how many jobs are submitted, and “singleton” queues, which allow only 1 job to be active.

    There are several other enhancements made to improve quality of life in v10:

    • All jobs have 2 retries enabled by default

    • FIPS compliant (dropped internal usage of MD5 hashing)

    • Replication support for HA or read-replicas (every table now has a primary key)

    • Serverless function supervision (maintain() function that can be run from another scheduler)

    • Postgres dependency-free (no pgcrypto extension needed uuid generation)

    • Dead letter queues (Replaces “completion job” feature and gains retry support for processing them)

    • What are your thoughts on things like pg_render which is a way to render HTML in Postgres? Is that going too far?

    Since I’m a Postgres fan, it’s hard for me to see how adding more capabilities to it would be considered “going too far”. This particular project appears to be a simple abstraction of other open source packages and could be a useful case study of creating a Postgres extension in Rust. Since this is compiled, it should even have better performance benchmarks over other packages with the same feature in non-compiled languages.

    Overall, I agree with the argument for simplicity in Stephan Schmidt’s article “Just Use Postgres for Everything”. The only issue with his article, which he continues to edit after all these years, is Stephan recommends River, a new OSS queue using SKIP LOCKED in Go, when we could have just mentioned little ole pg-boss that’s been around for years. The irony is that River was built by Brandur “don’t use Postgres queues” Leach. I’m kidding around here, of course, but who doesn’t enjoy a bit of irony?

    • What advice would you give to developers or companies who are thinking of open sourcing their projects?

    For developers, I would encourage starting off by making a contribution to a package you use daily. For example, if you’ve ever thought “I like this package, but I think it could be better if it had this feature”, that might be something you could add. If you have an idea of a new project, my advice would be to focus on the MVP (minimally viable product). The more features you add, the more time required to release it and the more maintenance required to keep it running. This is the primary reason I don’t include a web API or UI with pg-boss, even though I’m sure it would make it more popular.

    For companies, I would point to successful startups that became popular and attracted funding because of their OSS projects. TimescaleDB, Supabase, and Citus are examples just from the Postgres ecosystem.

    • What is the main reason you keep working on pg-boss? What do you get out of it?

    It’s nice to be able to change what type of development you do occasionally. It gives you a different perspective and usually gives you new insights into your primary job. When you have responsibility over a popular package, it also adds some motivation to make sure it remains healthy. It’s not a good feeling when your package causes bad performance on a database server because of its own success (a large queue backlog could mean your company is growing). I did sign up for GitHub Sponsors a couple years ago, and I appreciate every company and developer that has benefited from pg-boss making contributions, but it’s still far from being able to fund itself.

    • Have you ever thought of introducing a paid product on top of pg-boss? Why yes/no?

    I haven’t spent time evaluating what that would look like, but it is an intriguing idea for sure. If I was able to work on pg-boss full-time, there are several potential new concepts that could be explored now that partitioning and queue policies have been created.

    For example, someone recently opened an issue to request arbitrary JSON querying capability to be included in fetch(). If done globally across all queues, this would require indexing the jsonb payload, which in some cases could be large, slowing down reads and writes. However, if applied only to a single partition, this index could be isolated to only the queue that needs it via a new policy. Postgres allows different indexes and unique constraints between tables within the same partitioning hierarchy, which could be used for this policy.

    Furthermore, very large partitions could even have subpartitions, creating a tree-like structure for scalability purposes. This strategy has already been proven at scale in Postgres by the TimescaleDB team, and could potentially result in removing its storage capacity challenges entirely.

    Yet another area of exploration is encapsulating all features into Postgres functions to make the logic of pg-boss more easily integrated with non-Node.js platforms, as most of the logic in pg-boss is actually already pure SQL. Some have also mentioned to me that it would be nice if we had a standard queue data schema that could be shared across platforms, which sounds like a noble goal, but challenging since it would involve collaboration across OSS projects to complete.

    • Apart from yours, is there an open source tool or project you’re particularly excited about?

    I’m a big fan of Supabase at the moment. I’m currently evaluating their use of JWT claims and Postgres RLS for SaaS multi-tenancy. They have open sourced several of their projects as well, such as supavisor, a connection pooler. Their product also happens to use pg-boss internally, which means… “they use pg-boss btw” 🙂

    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/2024/09/17/from-idea-to-20k-in-days-how-wasp-accelerated-nuloapps-launch.html b/blog/2024/09/17/from-idea-to-20k-in-days-how-wasp-accelerated-nuloapps-launch.html index 6b82109663..a1188df56b 100644 --- a/blog/2024/09/17/from-idea-to-20k-in-days-how-wasp-accelerated-nuloapps-launch.html +++ b/blog/2024/09/17/from-idea-to-20k-in-days-how-wasp-accelerated-nuloapps-launch.html @@ -18,14 +18,14 @@ - - - + + +

    Built in Days, Acquired for $20K: The NuloApp Story

    · 6 min read
    Milica Maksimović

    Meet Kaloyan Stoyanov, a tech lead who turned his passion project into a full-fledged SaaS product, and sold it within days of launching it.

    A year before officially launching NuloApp, Kaloyan realized that many creators in the "faceless YouTube channels" niche were using tools like Opus.pro to generate short-form content from long-form videos, but these tools were very expensive. Without yet earning revenue from YouTube or TikTok, Kaloyan decided to take matters into his own hands, building his own tool in just a month.

    Initially, his tool automatically created and uploaded shorts, but after some time, when his channel didn’t pick up, he stopped the project. Fast forward to a year later, and YouTube's algorithm brought similar content back into his feed, reigniting his passion. This time, Kaloyan took it further by transforming his tool into a SaaS product: NuloApp.

    The Problem NuloApp Solves​

    NuloApp is an AI tool designed to make video content creation simpler by converting long-form videos into short clips that have the highest chance to capture audience’s attention. It resizes content from horizontal (landscape) to vertical (portrait) for platforms like YouTube Shorts, Instagram Reels, and TikTok, helping creators push content faster.

    Tech Stack Overview​

    • Framework: Wasp
    • Payment integration: Stripe
    • Other tools: OpenCV, FastAPI, Meta's llama, OpenAI's Whisper, LangChain
    • Database: PostgreSQL

    Programatically Editing Videos​

    The real genius behind NuloApp is the way that Kaloyan combined a number of tools to programatically edit the longer form videos and podcasts, into short, engaging clips for social media.

    First of all, OpenCV, an open-source computer vision library, was used as the main editing tool. This is how NuloApp is able to get the correct aspect ratio for smartphone content, and do other cool things like centering the video on the speaker so that they aren't out of frame when the aspect ratio is changed.

    In order to programtically get the correct clips to extract, AI tools like Meta's llama-3-70b LLM and OpenAI's Whisper were also used. Whisper allowed for fast speech-to-text transcription, which could then be passed on the llama in order to find segments worth extracting.

    Putting these tools together and accessible via a standalone API was the final step in this process. But this really clever combination of tools was just one part of puzzle. The next problem to solve was how to deliver it all as a SaaS app that users could pay for?

    Why Wasp?​

    When Kaloyan decided to relaunch his tool as a SaaS product, he didn’t have time to spare. He needed a framework that would allow him to build and deploy quickly. That’s where Wasp came in.

    “I was looking for a quick and easy-to-use boilerplate with most SaaS app features already pre-built so I could deploy faster,” says Kaloyan. Wasp’s SaaS boilerplate starter, with well-structured documentation, alongside its responsive Discord support, made it the ideal choice.

    The Impact of Wasp on Development​

    Kaloyan was particularly impressed with how Wasp simplified complex tasks that would normally take much longer to implement. From setting up Google logins and dark mode switches to creating hourly jobs, the development process was smoother than expected. “Everything—from enabling Google logins to creating hourly jobs I badly needed—was way too easy to set up.”.

    Auth and Stripe Integration Made Easy​

    One of Kaloyan’s least favorite tasks as a developer is building out authentication systems, and he found that even implementing third-party libraries could be frustrating. Fortunately, Wasp’s boilerplate made the process of setting up authentication and pre-configuring Stripe for payments seamless.

    Here's what wasp.config file looks like, through which you can define full-stack auth in a Wasp app.

    app myApp {
      wasp: {
        version: "^0.14.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the User entity
        userEntity: User,
        methods: {
          // 2. Enable Github Auth
          gitHub: {},
          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
            emailVerification: {
              clientRoute: EmailVerificationRoute, //this route/page should be created
            },
            passwordReset: {
              clientRoute: PasswordResetRoute, //this route/page should be created
            },
            // Add an emailSender -- Dummy just logs to console for dev purposes
            // but there are a ton of supported providers :D
            emailSender: {
              provider: Dummy,
            },
          },
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    And here's a 1 minute demo:


    Additionally, the framework's job scheduling features helped Kaloyan avoid the headache of configuring cron jobs on Docker containers.

    Fast Acquisition: From Launch to Sale in 24 Hours​

    Upon launching NuloApp, Kaloyan listed the product on Acquire with the primary goal of gathering feedback from potential buyers about what features or metrics they value most in a SaaS product. To his surprise, within the first day of listing, he received multiple offers. After a brief meeting with one interested buyer, they quickly agreed on a $20k deal, validating the product's value and market potential.

    NuloApp Homepage

    Advice for Builders Considering Wasp​

    If you're considering Wasp, Kaloyan’s advice is clear: Wasp is easy to get started with and flexible enough to build what you need without adding unnecessary complexity. For Kaloyan, Wasp was ideal because it handled the boilerplate while still giving him the freedom to customize as required. "The documentation is also solid, which definitely helps when you're moving quickly.”

    Next Steps​

    If you’d like to follow in Kaloyan’s footsteps, this is how to get started with the boilerplate he used.

    Open your terminal and install Wasp:

    curl -sSL https://get.wasp-lang.dev/installer.sh | sh

    From there you only need to run:

    wasp new -t saas

    That’s it, you’re one step closer to building your first SaaS!

    Feel free to join our Discord to connect with other builders and get support from the Wasp community. See you!

    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/2024/09/24/why-your-emails-arent-getting-delivered-and-how-to-fix-this-problem.html b/blog/2024/09/24/why-your-emails-arent-getting-delivered-and-how-to-fix-this-problem.html index a4948b03a8..a9a8ede927 100644 --- a/blog/2024/09/24/why-your-emails-arent-getting-delivered-and-how-to-fix-this-problem.html +++ b/blog/2024/09/24/why-your-emails-arent-getting-delivered-and-how-to-fix-this-problem.html @@ -18,14 +18,14 @@ - - - + + +

    Why Your SaaS Emails Aren’t Being Delivered and How to Fix This Issue

    · 5 min read
    Milica Maksimović

    If you’ve just built your SaaS web app and deployed it on a production server, you might be running into email deliverability issues. Transactional or marketing emails might not be landing in your users' inboxes. Don’t panic! This is a pretty common problem, especially for apps that run on newly registered domains.

    We have seen a lot of Wasp users facing similar challenges, thinking their toolkit was to blame. In our Discord community, we regularly help users who’ve just launched their first app with Wasp, and we've seen this issue pop up frequently. The bad news: your users and their email servers pulled a Gandalf move on you. The good news: no worries, this is something you can fix!

    Gandalf saying you shall not pass

    1. Build up your domain reputation​

    A new domain is often flagged as suspicious by email providers, causing your emails to land in spam or not be delivered at all. Google’s filtering is really heavy, especially if you’re trying to reach people with business addresses (user@theircompany.com). Even the basic signup confirmations have a high chance of bouncing when you’re sending them from a freshly registered domain.

    To improve your domain reputation, do the following:

    • Use a custom domain for your emails: If you’re still using a generic email service like Gmail, switch to a custom domain. This makes you more trustworthy and looks more professional.
    • Warm-up your domain: You need to do this before you start onboarding your users. Any type of sudden bursts of emails from a new domain can be flagged as spam. For example, if you decide to launch on Product Hunt, you’ll get a spike in signups which increases the amount of sent emails. It’s possible that this spike triggers the alarms, and people stop receiving your emails. There are numerous tools out there that can help you with this process. Don’t skip this step, it’s mandatory.
    • Keep the sending volume consistent: Regular email sending patterns are seen as trustworthy. Inconsistent or high-volume bursts from a new domain can trigger spam filters.

    2. Authenticate your domain​

    Authentication adds a layer of security to your emails, proving to email providers that you’re a legitimate sender and not the next prince of spam from the land of Spamlia. Here are the key records you need to set up with your DNS provider:

    • SPF: This allows email servers to verify that emails sent from your domain are really coming from you.
    • DKIM: This attaches a digital signature to your emails that enables email servers to confirm the email wasn’t tampered with in transit.
    • DMARC: this one helps you control how your email domain handles unauthenticated emails.

    Read more about these records and how to add them to your DNS servers here.

    A girl saying and you're going to fix it

    3. Use professional email sending tools​

    Instead of sending emails directly from your own server, consider using a third-party email service that specializes in this area. Tools like SendGrid or Mailgun have built-in features to help ensure your emails make it to the inbox. Wasp helps you to add them to your stack with minimal configuration needed on your end.

    They monitor and improve your domain reputation, manage bounces, and handle email authentication out-of-the-box. We’d recommend you to offload sending emails to them, so that you can focus on the core aspects of your business.

    4. Monitor your deliverability​

    It’s important to keep an eye on how your emails are performing. Look for key metrics like bounce rate, open rate, and spam complaints. Most email sending services provide insights into your email deliverability, allowing you to make adjustments before your reputation gets damaged.

    • Bounce rate: High bounce rates suggest you’re sending to invalid or outdated email addresses. Regularly clean your list to avoid this. If more than 3% of your emails bounce, your domain can get blocked by your email provider.
    • Spam complaints: High spam reports and complaints can also lead to email providers blocking your domain. If users are marking your emails as spam, reconsider the content and frequency of your emails. Also, please don’t buy email lists off of Internet, those will do you more harm than good.

    meme saying are you looking into buying email lists

    5. Create high-quality content​

    What you write matters too. Emails are poorly written are more likely to be marked as spam.

    • Use a clear subject line: Avoid clickbait or overly promotional language. Keep your subject lines clear and aligned with the content of your email. If your subject line is off, your email can directly land in spam or in the promotional inbox.
    • Personalize your emails: Address your users by their name and offer content that is relevant to their needs. Personalized emails tend to have higher open and click-through rates.
    • Avoid spammy-looking keywords: Words like “FREE,” “LIMITED OFFER,” and excessive use of exclamation marks can trigger spam filters. Keep your language professional and to the point. DON’T USE CAPS LOCK EVERYWHERE!

    Inbox access granted​

    you can do this gif

    We know that email delivery issues are frustrating, but they are solvable. Start small - implement one or two changes. First, authenticate your domain and then set up professional email sending tools, Wasp supports some out of the box.

    You can monitor the performance over time, and improve your approach with every batch of emails. It’s not about getting everything perfect from the start, but about making the right decisions before you start onboarding your 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/2024/09/30/wasp-launch-week-7.html b/blog/2024/09/30/wasp-launch-week-7.html index 1d0ba48758..cac7a0f54e 100644 --- a/blog/2024/09/30/wasp-launch-week-7.html +++ b/blog/2024/09/30/wasp-launch-week-7.html @@ -18,14 +18,14 @@ - - - + + +

    Wasp Launch Week #7: Modern Times ⚙️

    · 5 min read
    Matija Sosic

    Launch Week 7 is here

    Hey Wasp lovers 🐝 💛,

    as Charlie Chaplin would say - I'll be back! So are we - despite the vacation season and all the sunshine that kept distracting us, we kept ourselves busy. We closed the curtains and cranked those A/C's on, and brought to you a whole new release of Wasp, as fresh as a cucumber!

    Charnold
    You see? I wasn't lying!

    As always, we’ll present the fruits of our labour in a community call that will happen in exactly three days, on Monday, October 7th, 10.30 AM EDT / 4.30 PM CET! To reserve your spot, visit the event in our Discord server and mark yourself as interested.

    Join the kick-off event

    Do it now, so we have the whole weekend of looking forward to seeing you there! 🐝

    With a mandatory admin stuff and a bad joke (Charnold mashup above ICYMI) out of the way, let’s get to the “meaty” stuff and see what is this launch really all about!

    Why Modern Times?​

    Wasp couldn’t do its magic as well as it does without all the brilliant parts of the stack it uses under the hood - Prisma, React Router, TanStack Query, and many others. That means we also have to keep track of how these tools evolve and update their versions in Wasp (aka make them modern) - and that's exactly what we did for this release!

    This launch week isn't so much about introducing new, flashy features (although we have some, and yes, it's TypeScript SDK, and yes, you can try it out), but rather about making what we have better and more up-to-date.

    Let's take a look together at the nice things that v0.15 brings us:

    #1: Level up ⬆️: Prisma 5, React Router 6, Express.js​

    level up
    What you will feel like wielding the latest Wasp release (just imagine the flames are yellow).

    As mentioned above, we got to keep up with the trends! Here's what's new:

    • Upgraded Prisma to v5 - no major interface changes, but brings a lot of performance improvements which also make Wasp faster by default 🏎️
    • React Router is now at v6 - v6 has been around for a while (you can see the the main changes from v5 here) and it made the code even more compact and elegant.
    • We cleaned up and bumped a lot of other dependencies - including Express.js on which we base Wasp’s API layer and our type-safe RPC.

    #2: TS SDK early preview 🤩 - give it a spin and let us know what you think!​

    During the last launch week we gave you a hint of how the TS SDK for Wasp might look like, and the response we got from you was amazing! This is probably a single feature that has caused the most excitement in the community so far.

    excited
    Yep, that's right

    Motived by your response, we decided to keep the train going. We took your feedback and implemented the first version of TS SDK for you to actually try out!

    ts sdk code example

    This is still work in progress but things seem to be coming together quite nicely! We'd also be grateful to hear your thoughts on it once it is out.

    #3: MAGE now uses GPT-4o 🧠 🤖​

    upgrading me

    Your favorite AI-powered SaaS boilerplate starter, MAGE, has also received an update and now uses OpenAI’s latest model, GPT-4o.

    A quick refresher - we released MAGE about a year ago as a convenient way to kickstart your SaaS powered by React, Node.js, Tailwind, and of course Wasp. It’s been used to generate over 40,000 codebases and is still used daily by developers.

    Read more about it or go ahead and give it a spin - it's 100% free!

    #4: Hackathon incoming 💻 🍪​

    It’s been a while since we had our last hackathon, and we decided it’s about time we fixed that! For this one, we prepared a special treat for you - I don’t want to spoil too much in advance, but let’s just say it’s going to do something with cookie banners and how to make them as annoying as possible (whoops 🫢).

    Here’s a quick teaser for y’all:

    hackathon incoming
    This one at least gives you a chance

    #5: See you there! 🫵​

    Not if I see you first

    And that’s a wrap! I hope this got you excited as much as it got me and that you will join us for the Launch Week kick-off event on Monday! You’ll get to hear about all these features and more first hand from working on them, ask questions, and learn more about what’s coming next.

    Register for the event here, and make sure to mark yourself as interested 👇

    Join the kick-off event

    Stay in the loop​

    dont leave

    Every day, we'll update this page with the latest announcement of the day - to stay in the loop, follow us on Twitter/X and join our Discord - see you there!

    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/archive.html b/blog/archive.html index 95a7d509c1..313c256aad 100644 --- a/blog/archive.html +++ b/blog/archive.html @@ -18,14 +18,14 @@ - - - + + +

    Archive

    Archive

    2019

    2021

    2022

    2023

    2024

    - - + + \ No newline at end of file diff --git a/blog/tags.html b/blog/tags.html index 7be259957f..d13623cc7f 100644 --- a/blog/tags.html +++ b/blog/tags.html @@ -18,14 +18,14 @@ - - - + + +

    Tags

    - - + + \ No newline at end of file diff --git a/blog/tags/acquire.html b/blog/tags/acquire.html index 24af570356..60c03b493d 100644 --- a/blog/tags/acquire.html +++ b/blog/tags/acquire.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "acquire"

    View All Tags
    By Vinny
    7 min read

    Building and Selling a GPT Wrapper SaaS in 5 Months

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/agent.html b/blog/tags/agent.html index 10d8c80eaa..6ab9e5ac5b 100644 --- a/blog/tags/agent.html +++ b/blog/tags/agent.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "agent"

    View All Tags
    By Vinny
    27 min read

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

    Read more→
    By Vinny
    46 min read

    Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/ai.html b/blog/tags/ai.html index a8321d66a3..064e625a25 100644 --- a/blog/tags/ai.html +++ b/blog/tags/ai.html @@ -18,14 +18,14 @@ - - - + + +

    7 posts tagged with "ai"

    View All Tags
    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
    27 min read

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

    Read more →

    By Vinny
    46 min read

    Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

    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 Vinny
    3 min read

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

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/auth.html b/blog/tags/auth.html index 1f7811dec6..5339763456 100644 --- a/blog/tags/auth.html +++ b/blog/tags/auth.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "auth"

    View All Tags
    By Sam Jakshtis
    18 min read

    Wasp: The JavaScript Answer to Django for Web Development

    Read more→
    By Shayne Czyzewski
    4 min read

    Feature Announcement - New auth method (Google)

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/boilerplate.html b/blog/tags/boilerplate.html index b5dfa8729d..cead0c6d10 100644 --- a/blog/tags/boilerplate.html +++ b/blog/tags/boilerplate.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "boilerplate"

    View All Tags
    By Vinny
    7 min read

    Building and Selling a GPT Wrapper SaaS in 5 Months

    Read more→
    By Vinny
    10 min read

    Open SaaS: our free, open-source SaaS starter

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/builders.html b/blog/tags/builders.html index 022ef09099..108393ef1d 100644 --- a/blog/tags/builders.html +++ b/blog/tags/builders.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "builders"

    View All Tags
    By Milica Maksimović
    6 min read

    Built in Days, Acquired for $20K: The NuloApp Story

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/career.html b/blog/tags/career.html index 63bc4fe171..0bf2a10916 100644 --- a/blog/tags/career.html +++ b/blog/tags/career.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "career"

    View All Tags
    By Vinny
    12 min read

    How to get a Web Dev Job in 2024

    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/chakra.html b/blog/tags/chakra.html index 5e5a693685..b00a4c364b 100644 --- a/blog/tags/chakra.html +++ b/blog/tags/chakra.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "chakra"

    View All Tags
    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/chatgpt.html b/blog/tags/chatgpt.html index 5791119535..c426e1c60c 100644 --- a/blog/tags/chatgpt.html +++ b/blog/tags/chatgpt.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "chatgpt"

    View All Tags
    By Vinny
    3 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/clean-code.html b/blog/tags/clean-code.html index c84e9a100b..e263773e24 100644 --- a/blog/tags/clean-code.html +++ b/blog/tags/clean-code.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "clean-code"

    View All Tags
    By Matija Sosic
    14 min read

    On the Importance of RFCs in Programming

    Read more→
    By Martin Sosic
    12 min read

    On the Importance of Naming in Programming

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/css.html b/blog/tags/css.html index 2783d4589d..36fc831002 100644 --- a/blog/tags/css.html +++ b/blog/tags/css.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "css"

    View All Tags
    By Shayne Czyzewski
    3 min read

    Feature Announcement - Tailwind CSS support

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/database.html b/blog/tags/database.html index dd97cd7996..a0087bd318 100644 --- a/blog/tags/database.html +++ b/blog/tags/database.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "database"

    View All Tags
    By Milica Maksimović
    13 min read

    The Faces Behind Open Source Projects: Tim Jones and pg-boss

    Read more→
    By Martin Sosic
    6 min read

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

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/discord.html b/blog/tags/discord.html index 3da9dd50f5..90b13929aa 100644 --- a/blog/tags/discord.html +++ b/blog/tags/discord.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "discord"

    View All Tags
    By Martin Sosic
    9 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/django.html b/blog/tags/django.html index defb75c5c0..852ab064e0 100644 --- a/blog/tags/django.html +++ b/blog/tags/django.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "django"

    View All Tags
    By Sam Jakshtis
    18 min read

    Wasp: The JavaScript Answer to Django for Web Development

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/emails.html b/blog/tags/emails.html index fee08eccd5..15eb455442 100644 --- a/blog/tags/emails.html +++ b/blog/tags/emails.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "emails"

    View All Tags
    By Milica Maksimović
    5 min read

    Why Your SaaS Emails Aren’t Being Delivered and How to Fix This Issue

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/express.html b/blog/tags/express.html index 3dc92339ef..727d50781a 100644 --- a/blog/tags/express.html +++ b/blog/tags/express.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "express"

    View All Tags
    By Vinny
    22 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/feature.html b/blog/tags/feature.html index ed1010d0d0..f65eb2f6ac 100644 --- a/blog/tags/feature.html +++ b/blog/tags/feature.html @@ -18,14 +18,14 @@ - - - + + +

    5 posts tagged with "feature"

    View All Tags
    By Filip Sodić
    7 min read

    Feature Release Announcement - Wasp Optimistic Updates

    Read more→
    By Filip Sodić
    8 min read

    Feature Announcement - TypeScript Support

    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 Shayne Czyzewski
    7 min read

    Feature Announcement - Wasp Jobs

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/framework.html b/blog/tags/framework.html index 6cfd814aa1..4c7d157005 100644 --- a/blog/tags/framework.html +++ b/blog/tags/framework.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "framework"

    View All Tags
    By Vinny
    12 min read

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

    Read more→
    By Vinny
    3 min read

    The Best Web App Framework Doesn't Exist

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/full-stack.html b/blog/tags/full-stack.html index 3d98831199..502786f760 100644 --- a/blog/tags/full-stack.html +++ b/blog/tags/full-stack.html @@ -18,14 +18,14 @@ - - - + + +

    5 posts tagged with "full-stack"

    View All Tags
    By Sam Jakshtis
    18 min read

    Wasp: The JavaScript Answer to Django for Web Development

    Read more→
    By Vinny
    12 min read

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

    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 Mihovil Ilakovac
    14 min read

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

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/fullstack.html b/blog/tags/fullstack.html index ec8395198c..c51ced95b0 100644 --- a/blog/tags/fullstack.html +++ b/blog/tags/fullstack.html @@ -18,14 +18,14 @@ - - - + + +

    7 posts tagged with "fullstack"

    View All Tags
    By Vinny
    27 min read

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

    Read more→
    By Vinny
    46 min read

    Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

    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 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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/function-calling.html b/blog/tags/function-calling.html index 5d987f80b3..edf3ed49ae 100644 --- a/blog/tags/function-calling.html +++ b/blog/tags/function-calling.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "function calling"

    View All Tags
    By Vinny
    31 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/generate.html b/blog/tags/generate.html index f29a116fd6..242c7987c4 100644 --- a/blog/tags/generate.html +++ b/blog/tags/generate.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "generate"

    View All Tags
    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/github.html b/blog/tags/github.html index be103551e9..80faf7c1cc 100644 --- a/blog/tags/github.html +++ b/blog/tags/github.html @@ -18,14 +18,14 @@ - - - + + +

    13 posts tagged with "github"

    View All Tags
    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
    6 min read

    Wasp Beta - February 2023

    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 Matija Sosic
    3 min read

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

    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 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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/gitpod.html b/blog/tags/gitpod.html index 34348f5b41..7de482cb1b 100644 --- a/blog/tags/gitpod.html +++ b/blog/tags/gitpod.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "gitpod"

    View All Tags
    By Maksym Khamrovskyi
    4 min read

    How to win a hackathon. Brief manual.

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/gpt.html b/blog/tags/gpt.html index 14c28387ff..6960faa0a4 100644 --- a/blog/tags/gpt.html +++ b/blog/tags/gpt.html @@ -18,14 +18,14 @@ - - - + + +

    7 posts tagged with "gpt"

    View All Tags
    By Vinny
    7 min read

    Building and Selling a GPT Wrapper SaaS in 5 Months

    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
    46 min read

    Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/hack.html b/blog/tags/hack.html index fd04e18230..c8220bd6e0 100644 --- a/blog/tags/hack.html +++ b/blog/tags/hack.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "hack"

    View All Tags
    By Vinny
    9 min read

    Using Product Requirement Documents to Generate Better Web Apps with AI

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/hackathon.html b/blog/tags/hackathon.html index 96befae83c..361ca86fae 100644 --- a/blog/tags/hackathon.html +++ b/blog/tags/hackathon.html @@ -18,14 +18,14 @@ - - - + + +

    3 posts tagged with "hackathon"

    View All Tags
    By Vinny
    6 min read

    Hackathon #2: Results & Review

    Read more→
    By Vinny
    6 min read

    Hosting Our First Hackathon: Results & Review

    Read more →

    By Maksym Khamrovskyi
    4 min read

    How to win a hackathon. Brief manual.

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/hacktoberfest.html b/blog/tags/hacktoberfest.html index 67368307c7..1f66fae5d0 100644 --- a/blog/tags/hacktoberfest.html +++ b/blog/tags/hacktoberfest.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "hacktoberfest"

    View All Tags
    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 Maksym Khamrovskyi
    6 min read

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

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/haskell.html b/blog/tags/haskell.html index 9a2940b792..1ff99bd81c 100644 --- a/blog/tags/haskell.html +++ b/blog/tags/haskell.html @@ -18,14 +18,14 @@ - - - + + +

    3 posts tagged with "haskell"

    View All Tags
    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 Martin Sosic
    9 min read

    Tutorial: `forall` in Haskell

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/hiring.html b/blog/tags/hiring.html index 121d42e323..af83fcdb2b 100644 --- a/blog/tags/hiring.html +++ b/blog/tags/hiring.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "hiring"

    View All Tags
    By Vasili Shynkarenka
    31 min read

    How to communicate why your startup is worth joining

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/indie-hacker.html b/blog/tags/indie-hacker.html index 7cd0daaacf..e9226fad33 100644 --- a/blog/tags/indie-hacker.html +++ b/blog/tags/indie-hacker.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "IndieHacker"

    View All Tags
    By Vinny
    8 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/interview.html b/blog/tags/interview.html index 21e3951b60..2adf4b4810 100644 --- a/blog/tags/interview.html +++ b/blog/tags/interview.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "Interview"

    View All Tags
    By Vinny
    8 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/javascript.html b/blog/tags/javascript.html index ea9584f11f..c7bc37d7d9 100644 --- a/blog/tags/javascript.html +++ b/blog/tags/javascript.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "javascript"

    View All Tags
    By Vinny
    12 min read

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

    Read more→
    By Filip Sodić
    8 min read

    Feature Announcement - TypeScript Support

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/job.html b/blog/tags/job.html index 2c6397efdf..3db832af18 100644 --- a/blog/tags/job.html +++ b/blog/tags/job.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "job"

    View All Tags
    By Vinny
    12 min read

    How to get a Web Dev Job in 2024

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/jobs.html b/blog/tags/jobs.html index 4c27c87f3b..66015abb73 100644 --- a/blog/tags/jobs.html +++ b/blog/tags/jobs.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "jobs"

    View All Tags
    By Shayne Czyzewski
    7 min read

    Feature Announcement - Wasp Jobs

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/junior-developers.html b/blog/tags/junior-developers.html index cde86fdcf1..40efd06425 100644 --- a/blog/tags/junior-developers.html +++ b/blog/tags/junior-developers.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "Junior Developers"

    View All Tags
    By Vinny
    4 min read

    10 "Hard Truths" All Junior Developers Need to Hear

    Read more→
    By Vinny
    6 min read

    The Most Common Misconceptions Amongst Junior Developers

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/langchain.html b/blog/tags/langchain.html index a51a87fdd5..e6040ea835 100644 --- a/blog/tags/langchain.html +++ b/blog/tags/langchain.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "langchain"

    View All Tags
    By Vinny
    27 min read

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

    Read more→
    By Vinny
    46 min read

    Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/language.html b/blog/tags/language.html index 7ef444e37d..7f276cc411 100644 --- a/blog/tags/language.html +++ b/blog/tags/language.html @@ -18,14 +18,14 @@ - - - + + +

    5 posts tagged with "language"

    View All Tags
    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 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 Matija Sosic
    11 min read

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

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/laravel.html b/blog/tags/laravel.html index 2c41f25caf..afa2aa31a6 100644 --- a/blog/tags/laravel.html +++ b/blog/tags/laravel.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "laravel"

    View All Tags
    By Vinny
    12 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/launch-week.html b/blog/tags/launch-week.html index e632f01732..4cb751b427 100644 --- a/blog/tags/launch-week.html +++ b/blog/tags/launch-week.html @@ -18,14 +18,14 @@ - - - + + +

    8 posts tagged with "launch-week"

    View All Tags
    By Matija Sosic
    5 min read

    Wasp Launch Week #7: Modern Times ⚙️

    Read more→
    By Matija Sosic
    5 min read

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

    Read more →

    By Matija Sosic
    5 min read

    Wasp Launch Week #5: Waspnado 🐝 🌪️

    Read more →

    By Matija Sosic
    5 min read

    Wasp Launch Week #4: Waspolution

    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 Matija Sosic
    6 min read

    Wasp Launch Week #3: Magic

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/mage.html b/blog/tags/mage.html index 360594189e..c58b218160 100644 --- a/blog/tags/mage.html +++ b/blog/tags/mage.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "mage"

    View All Tags
    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/marketing.html b/blog/tags/marketing.html index 29dd6d82da..f2ce6d39f3 100644 --- a/blog/tags/marketing.html +++ b/blog/tags/marketing.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "marketing"

    View All Tags
    By Vinny
    7 min read

    Building and Selling a GPT Wrapper SaaS in 5 Months

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/meme.html b/blog/tags/meme.html index b113d051e7..1da0aae50c 100644 --- a/blog/tags/meme.html +++ b/blog/tags/meme.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "meme"

    View All Tags
    By Vinny
    31 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/ml.html b/blog/tags/ml.html index 6e0298c0b1..85ebfd9bd2 100644 --- a/blog/tags/ml.html +++ b/blog/tags/ml.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "ML"

    View All Tags
    By Matija Sosic
    11 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/new-hire.html b/blog/tags/new-hire.html index a5301f8534..8d249cd8aa 100644 --- a/blog/tags/new-hire.html +++ b/blog/tags/new-hire.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "new-hire"

    View All Tags
    By Matija Sosic
    6 min read

    Meet the team - Filip Sodić, Founding Engineer

    Read more→
    By Matija Sosic
    4 min read

    Meet the team - Shayne Czyzewski, Founding Engineer

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/nextjs.html b/blog/tags/nextjs.html index 35f10bed54..e3fe6a859b 100644 --- a/blog/tags/nextjs.html +++ b/blog/tags/nextjs.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "nextjs"

    View All Tags
    By Lucas Lima do Nascimento
    15 min read

    How to Add Auth with Lucia to Your React/Next.js App - A Step by Step Guide

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/node.html b/blog/tags/node.html index d4aaa11ffb..10d602a59d 100644 --- a/blog/tags/node.html +++ b/blog/tags/node.html @@ -18,14 +18,14 @@ - - - + + +

    3 posts tagged with "node"

    View All Tags
    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 Vinny
    46 min read

    Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/nodejs.html b/blog/tags/nodejs.html index 4ef2c5f4c8..b779d71f22 100644 --- a/blog/tags/nodejs.html +++ b/blog/tags/nodejs.html @@ -18,14 +18,14 @@ - - - + + +

    3 posts tagged with "nodejs"

    View All Tags
    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 Martin Sosic
    9 min read

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

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/open-source.html b/blog/tags/open-source.html index 9b2464f654..f7122d0019 100644 --- a/blog/tags/open-source.html +++ b/blog/tags/open-source.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "open-source"

    View All Tags
    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→
    - - + + \ No newline at end of file diff --git a/blog/tags/openai.html b/blog/tags/openai.html index 642fd5e108..0c25fe3f58 100644 --- a/blog/tags/openai.html +++ b/blog/tags/openai.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "openai"

    View All Tags
    By Vinny
    7 min read

    Building and Selling a GPT Wrapper SaaS in 5 Months

    Read more→
    By Vinny
    31 min read

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

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/optimistic.html b/blog/tags/optimistic.html index ea12a8cf7b..52898e3627 100644 --- a/blog/tags/optimistic.html +++ b/blog/tags/optimistic.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "optimistic"

    View All Tags
    By Filip Sodić
    7 min read

    Feature Release Announcement - Wasp Optimistic Updates

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/os-maintainers.html b/blog/tags/os-maintainers.html index 36871a677e..00c85196bc 100644 --- a/blog/tags/os-maintainers.html +++ b/blog/tags/os-maintainers.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "os-maintainers"

    View All Tags
    By Milica Maksimović
    13 min read

    The Faces Behind Open Source Projects: Tim Jones and pg-boss

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/pern.html b/blog/tags/pern.html index aff876d60c..6b59efb880 100644 --- a/blog/tags/pern.html +++ b/blog/tags/pern.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "PERN"

    View All Tags
    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/postgresql.html b/blog/tags/postgresql.html index 2b23d175a5..8e820a6ce1 100644 --- a/blog/tags/postgresql.html +++ b/blog/tags/postgresql.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "postgresql"

    View All Tags
    By Milica Maksimović
    13 min read

    The Faces Behind Open Source Projects: Tim Jones and pg-boss

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/prd.html b/blog/tags/prd.html index 31b7eca2f5..f2e920cf80 100644 --- a/blog/tags/prd.html +++ b/blog/tags/prd.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "prd"

    View All Tags
    By Vinny
    9 min read

    Using Product Requirement Documents to Generate Better Web Apps with AI

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/prisma.html b/blog/tags/prisma.html index 6e91f63528..74d8656ba2 100644 --- a/blog/tags/prisma.html +++ b/blog/tags/prisma.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "prisma"

    View All Tags
    By Martin Sosic
    6 min read

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

    Read more→
    By Martin Sosic
    7 min read

    Why we chose Prisma as a database layer for Wasp

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/product-requirement.html b/blog/tags/product-requirement.html index b08579b2c9..421754244d 100644 --- a/blog/tags/product-requirement.html +++ b/blog/tags/product-requirement.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "product requirement"

    View All Tags
    By Vinny
    9 min read

    Using Product Requirement Documents to Generate Better Web Apps with AI

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/product-update.html b/blog/tags/product-update.html index b77c0c3541..4274fe718c 100644 --- a/blog/tags/product-update.html +++ b/blog/tags/product-update.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "product-update"

    View All Tags
    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/programming.html b/blog/tags/programming.html index 9a128384d3..9850fb011d 100644 --- a/blog/tags/programming.html +++ b/blog/tags/programming.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "programming"

    View All Tags
    By Matija Sosic
    14 min read

    On the Importance of RFCs in Programming

    Read more→
    By Martin Sosic
    12 min read

    On the Importance of Naming in Programming

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/rails.html b/blog/tags/rails.html index 34900dc1d6..c5455dc398 100644 --- a/blog/tags/rails.html +++ b/blog/tags/rails.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "rails"

    View All Tags
    By Vinny
    12 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/react.html b/blog/tags/react.html index 0cbeb8152c..61d5e9d210 100644 --- a/blog/tags/react.html +++ b/blog/tags/react.html @@ -18,14 +18,14 @@ - - - + + +

    12 posts tagged with "react"

    View All Tags
    By Sam Jakshtis
    18 min read

    Wasp: The JavaScript Answer to Django for Web Development

    Read more→
    By Lucas Lima do Nascimento
    15 min read

    How to Add Auth with Lucia to Your React/Next.js App - A Step by Step Guide

    Read more →

    By Vinny
    7 min read

    Building and Selling a GPT Wrapper SaaS in 5 Months

    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 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 Vinny
    46 min read

    Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

    Read more →

    By Matija Sosic
    5 min read

    New React docs pretend SPAs don't exist anymore

    Read more →

    By Vinny
    3 min read

    The Best Web App Framework Doesn't Exist

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/real-time.html b/blog/tags/real-time.html index 3078b837d6..5cd85f7af4 100644 --- a/blog/tags/real-time.html +++ b/blog/tags/real-time.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "real-time"

    View All Tags
    By Vinny
    22 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/reddit.html b/blog/tags/reddit.html index e201aef81c..52d5d2d9d1 100644 --- a/blog/tags/reddit.html +++ b/blog/tags/reddit.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "Reddit"

    View All Tags
    By Vinny
    4 min read

    10 "Hard Truths" All Junior Developers Need to Hear

    Read more→
    By Vinny
    6 min read

    The Most Common Misconceptions Amongst Junior Developers

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/saa-s.html b/blog/tags/saa-s.html index b16dba9f47..48a2feef5e 100644 --- a/blog/tags/saa-s.html +++ b/blog/tags/saa-s.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "SaaS"

    View All Tags
    By Vinny
    8 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/saas.html b/blog/tags/saas.html index d7414cf246..631a728114 100644 --- a/blog/tags/saas.html +++ b/blog/tags/saas.html @@ -18,14 +18,14 @@ - - - + + +

    5 posts tagged with "saas"

    View All Tags
    By Milica Maksimović
    6 min read

    Built in Days, Acquired for $20K: The NuloApp Story

    Read more→
    By Vinny
    7 min read

    Building and Selling a GPT Wrapper SaaS in 5 Months

    Read more →

    By Vinny
    10 min read

    Open SaaS: our free, open-source SaaS starter

    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/showcase.html b/blog/tags/showcase.html index f6ac679e7b..588804f558 100644 --- a/blog/tags/showcase.html +++ b/blog/tags/showcase.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "showcase"

    View All Tags
    By Milica Maksimović
    6 min read

    Built in Days, Acquired for $20K: The NuloApp Story

    Read more→
    By Matija Sosic
    4 min read

    What can you build with Wasp?

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/solopreneur.html b/blog/tags/solopreneur.html index 8a89bb3069..065bb1f67a 100644 --- a/blog/tags/solopreneur.html +++ b/blog/tags/solopreneur.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "Solopreneur"

    View All Tags
    By Vinny
    8 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/startup.html b/blog/tags/startup.html index 1596d8ddf7..76470c2daa 100644 --- a/blog/tags/startup.html +++ b/blog/tags/startup.html @@ -18,14 +18,14 @@ - - - + + +

    3 posts tagged with "startup"

    View All Tags
    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
    4 min read

    Journey to YCombinator

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/startups.html b/blog/tags/startups.html index 28b188373f..9ac5f4545b 100644 --- a/blog/tags/startups.html +++ b/blog/tags/startups.html @@ -18,14 +18,14 @@ - - - + + +

    15 posts tagged with "startups"

    View All Tags
    By Vinny
    6 min read

    Hackathon #2: Results & Review

    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
    6 min read

    Wasp Beta - February 2023

    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 Matija Sosic
    3 min read

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

    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 Matija Sosic
    7 min read

    Alpha Testing Program: post-mortem

    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 Vasili Shynkarenka
    31 min read

    How to communicate why your startup is worth joining

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/state-of-js.html b/blog/tags/state-of-js.html index 0c93946cde..b55a4b1a6e 100644 --- a/blog/tags/state-of-js.html +++ b/blog/tags/state-of-js.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "StateOfJS"

    View All Tags
    By Vinny
    3 min read

    The Best Web App Framework Doesn't Exist

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/stripe.html b/blog/tags/stripe.html index c9300b7c87..77ed5d05d6 100644 --- a/blog/tags/stripe.html +++ b/blog/tags/stripe.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "stripe"

    View All Tags
    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/supabase.html b/blog/tags/supabase.html index 7060ae7fd5..94a69cc964 100644 --- a/blog/tags/supabase.html +++ b/blog/tags/supabase.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "Supabase"

    View All Tags
    By Mihovil Ilakovac
    14 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/tech-career.html b/blog/tags/tech-career.html index f547bbf071..34200329fe 100644 --- a/blog/tags/tech-career.html +++ b/blog/tags/tech-career.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "Tech Career"

    View All Tags
    By Vinny
    4 min read

    10 "Hard Truths" All Junior Developers Need to Hear

    Read more→
    By Vinny
    6 min read

    The Most Common Misconceptions Amongst Junior Developers

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/tech.html b/blog/tags/tech.html index 0498708fde..4c18ed56a4 100644 --- a/blog/tags/tech.html +++ b/blog/tags/tech.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "tech"

    View All Tags
    By Lucas Lima do Nascimento
    15 min read

    How to Add Auth with Lucia to Your React/Next.js App - A Step by Step Guide

    Read more→
    By Vinny
    12 min read

    How to get a Web Dev Job in 2024

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/tips.html b/blog/tags/tips.html index 0101ed4d40..7cf2234fb8 100644 --- a/blog/tags/tips.html +++ b/blog/tags/tips.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "tips"

    View All Tags
    By Milica Maksimović
    5 min read

    Why Your SaaS Emails Aren’t Being Delivered and How to Fix This Issue

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/tutorial.html b/blog/tags/tutorial.html index 53b129319e..9c14017857 100644 --- a/blog/tags/tutorial.html +++ b/blog/tags/tutorial.html @@ -18,14 +18,14 @@ - - - + + +

    4 posts tagged with "tutorial"

    View All Tags
    By Sam Jakshtis
    18 min read

    Wasp: The JavaScript Answer to Django for Web Development

    Read more→
    By Lucas Lima do Nascimento
    15 min read

    How to Add Auth with Lucia to Your React/Next.js App - A Step by Step Guide

    Read more →

    By Boris Martinović
    10 min read

    A Guide to Windows Development with Wasp & WSL

    Read more →

    By Martin Sosic
    9 min read

    Tutorial: `forall` in Haskell

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/typescript.html b/blog/tags/typescript.html index 228d3ec00c..c40129eed3 100644 --- a/blog/tags/typescript.html +++ b/blog/tags/typescript.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "typescript"

    View All Tags
    By Vinny
    22 min read

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

    Read more→
    By Filip Sodić
    8 min read

    Feature Announcement - TypeScript Support

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/update.html b/blog/tags/update.html index 57eac44d10..cb185de56f 100644 --- a/blog/tags/update.html +++ b/blog/tags/update.html @@ -18,14 +18,14 @@ - - - + + +

    6 posts tagged with "update"

    View All Tags
    By Matija Sosic
    5 min read

    Wasp Launch Week #7: Modern Times ⚙️

    Read more→
    By Matija Sosic
    5 min read

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

    Read more →

    By Matija Sosic
    5 min read

    Wasp Launch Week #5: Waspnado 🐝 🌪️

    Read more →

    By Matija Sosic
    5 min read

    Wasp Launch Week #4: Waspolution

    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/updates.html b/blog/tags/updates.html index 78e8a88fb5..b809885a6c 100644 --- a/blog/tags/updates.html +++ b/blog/tags/updates.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "updates"

    View All Tags
    By Filip Sodić
    7 min read

    Feature Release Announcement - Wasp Optimistic Updates

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/wasp-ai.html b/blog/tags/wasp-ai.html index ef94147d4d..fa6bf63a4e 100644 --- a/blog/tags/wasp-ai.html +++ b/blog/tags/wasp-ai.html @@ -18,14 +18,14 @@ - - - + + +

    2 posts tagged with "wasp-ai"

    View All Tags
    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 →

    - - + + \ No newline at end of file diff --git a/blog/tags/wasp.html b/blog/tags/wasp.html index df935b2438..342bded099 100644 --- a/blog/tags/wasp.html +++ b/blog/tags/wasp.html @@ -18,14 +18,14 @@ - - - + + +

    43 posts tagged with "wasp"

    View All Tags
    By Milica Maksimović
    6 min read

    Built in Days, Acquired for $20K: The NuloApp Story

    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 Vinny
    46 min read

    Build Your Own Personal Twitter Agent 🧠🐦⛓ with LangChain

    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 Mihovil Ilakovac
    14 min read

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

    Read more →

    By Matija Sosic
    6 min read

    Wasp Beta - February 2023

    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
    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 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
    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/tags/web-dev.html b/blog/tags/web-dev.html index e398577c4b..b6343251c9 100644 --- a/blog/tags/web-dev.html +++ b/blog/tags/web-dev.html @@ -18,14 +18,14 @@ - - - + + +

    3 posts tagged with "WebDev"

    View All Tags
    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 Vinny
    6 min read

    The Most Common Misconceptions Amongst Junior Developers

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/web-development.html b/blog/tags/web-development.html index 8b993986ef..0c19e952e1 100644 --- a/blog/tags/web-development.html +++ b/blog/tags/web-development.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "web-development"

    View All Tags
    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→
    - - + + \ No newline at end of file diff --git a/blog/tags/webdev.html b/blog/tags/webdev.html index 20843840dc..e690973dd7 100644 --- a/blog/tags/webdev.html +++ b/blog/tags/webdev.html @@ -18,14 +18,14 @@ - - - + + +

    36 posts tagged with "webdev"

    View All Tags
    By Milica Maksimović
    5 min read

    Why Your SaaS Emails Aren’t Being Delivered and How to Fix This Issue

    Read more→
    By Milica Maksimović
    6 min read

    Built in Days, Acquired for $20K: The NuloApp Story

    Read more →

    By Milica Maksimović
    13 min read

    The Faces Behind Open Source Projects: Tim Jones and pg-boss

    Read more →

    By Sam Jakshtis
    18 min read

    Wasp: The JavaScript Answer to Django for Web Development

    Read more →

    By Lucas Lima do Nascimento
    15 min read

    How to Add Auth with Lucia to Your React/Next.js App - A Step by Step Guide

    Read more →

    By Vinny
    12 min read

    How to get a Web Dev Job in 2024

    Read more →

    By Vinny
    6 min read

    Hackathon #2: Results & Review

    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 Matija Sosic
    6 min read

    Wasp Beta - February 2023

    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 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 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 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 Shayne Czyzewski
    5 min read

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

    Read more →

    By Matija Sosic
    10 min read

    How we built a Trello clone with Wasp - Waspello!

    Read more →

    - - + + \ No newline at end of file diff --git a/blog/tags/websockets.html b/blog/tags/websockets.html index c48d1e5844..3baae1ec09 100644 --- a/blog/tags/websockets.html +++ b/blog/tags/websockets.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "websockets"

    View All Tags
    By Vinny
    22 min read

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

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/windows.html b/blog/tags/windows.html index 83fcd7e98d..3c3ca62644 100644 --- a/blog/tags/windows.html +++ b/blog/tags/windows.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "windows"

    View All Tags
    By Boris Martinović
    10 min read

    A Guide to Windows Development with Wasp & WSL

    Read more→
    - - + + \ No newline at end of file diff --git a/blog/tags/wsl.html b/blog/tags/wsl.html index e7147a7a5c..231d7a027b 100644 --- a/blog/tags/wsl.html +++ b/blog/tags/wsl.html @@ -18,14 +18,14 @@ - - - + + +

    One post tagged with "wsl"

    View All Tags
    By Boris Martinović
    10 min read

    A Guide to Windows Development with Wasp & WSL

    Read more→
    - - + + \ No newline at end of file diff --git a/docs.html b/docs.html index 52a7869066..b8a4e57ffe 100644 --- a/docs.html +++ b/docs.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ which are in their essence Node.js functions that execute on the server and can, thanks to Wasp, very easily be called from the client.

    First, we define these Operations in our main.wasp file, so Wasp knows about them and can "beef them up":

    main.wasp
    // Queries have automatic cache invalidation and are type-safe.
    query getRecipes {
      fn: import { getRecipes } from "@src/recipe/operations",
      entities: [Recipe],
    }

    // Actions are type-safe and can be used to perform side-effects.
    action addRecipe {
      fn: import { addRecipe } from "@src/recipe/operations",
      entities: [Recipe],
    }

    ... and then implement them in our Javascript (or TypeScript) code (we show just the query here, using TypeScript):

    src/recipe/operations.ts
    // Wasp generates the types for you.
    import { type GetRecipes } from "wasp/server/operations";
    import { type Recipe } from "wasp/entities";

    export const getRecipes: GetRecipes<{}, Recipe[]> = async (_args, context) => {
      return context.entities.Recipe.findMany( // Prisma query
        { where: { user: { id: context.user.id } } }
      );
    };

    export const addRecipe ...

    Now we can very easily use these in our React components!

    For the end, let's create a home page of our app.

    First, we define it in main.wasp:

    main.wasp
    ...

    route HomeRoute { path: "/", to: HomePage }
    page HomePage {
      component: import { HomePage } from "@src/pages/HomePage",
      authRequired: true // Will send user to /login if not authenticated.
    }

    and then implement it as a React component in JS/TS (that calls the Operations we previously defined):

    src/pages/HomePage.tsx
    import { useQuery, getRecipes } from 'wasp/client/operations'
    import { type User } from 'wasp/entities'

    export function HomePage({ user }: { user: User }) {
      // Due to full-stack type safety, `recipes` will be of type `Recipe[]` here.
      const { data: recipes, isLoading } = useQuery(getRecipes) // Calling our query here!

      if (isLoading) {
        return <div>Loading...</div>
      }

      return (
        <div>
          <h1>Recipes</h1>
          <ul>
            {recipes
              ? recipes.map((recipe) => (
                  <li key={recipe.id}>
                    <div>{recipe.title}</div>
                    <div>{recipe.description}</div>
                  </li>
                ))
              : 'No recipes defined yet!'}
          </ul>
        </div>
      )
    }

    And voila! We are listing all the recipes in our app 🎉

    This was just a quick example to give you a taste of what Wasp is. For step by step tour through the most important Wasp features, check out the Todo app tutorial.

    note

    Above we skipped defining /login and /signup pages to keep the example a bit shorter, but those are very simple to do by using Wasp's Auth UI feature.

    When to use Wasp​

    Wasp addresses the same core problems that typical web app frameworks are addressing, and it in big part looks, swims and quacks like a web app framework.

    Best used for​

    • building full-stack web apps (like e.g. Airbnb or Asana)
    • quickly starting a web app with industry best practices
    • to be used alongside modern web dev stack (React and Node.js are currently supported)

    Avoid using Wasp for​

    • building static/presentational websites
    • to be used as a no-code solution
    • to be a solve-it-all tool in a single language

    Wasp is a DSL​

    note

    You don't need to know what a DSL is to use Wasp, but if you are curious, you can read more about it below.

    Wasp does not match typical expectations of a web app framework: it is not a set of libraries, it is instead a simple programming language that understands your code and can do a lot of things for you.

    Wasp is a programming language, but a specific kind: it is specialized for a single purpose: building modern web applications. We call such languages DSLs (Domain Specific Language).

    Other examples of DSLs that are often used today are e.g. SQL for databases and HTML for web page layouts. The main advantage and reason why DSLs exist is that they need to do only one task (e.g. database queries) so they can do it well and provide the best possible experience for the developer.

    The same idea stands behind Wasp - a language that will allow developers to build modern web applications with 10x less code and less stack-specific knowledge.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8.html b/docs/0.11.8.html index 7624c9fe30..92aca5adb4 100644 --- a/docs/0.11.8.html +++ b/docs/0.11.8.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -30,7 +30,7 @@ which are in their essence a Node.js functions that execute on server and can, thanks to Wasp, very easily be called from the client.

    First, we define these Operations in our main.wasp file, so Wasp knows about them and can "beef them up":

    main.wasp
    // Queries have automatic cache invalidation and are type-safe.
    query getRecipes {
      fn: import { getRecipes } from "@server/recipe.js",
      entities: [Recipe],
    }

    // Actions are type-safe and can be used to perform side-effects.
    action addRecipe {
      fn: import { addRecipe } from "@server/recipe.js",
      entities: [Recipe],
    }

    ... and then implement them in our Javascript (or TypeScript) code (we show just the query here, using TypeScript):

    src/server/recipe.ts
    // Wasp generates types for you.
    import type { GetRecipes } from "@wasp/queries/types";
    import type { Recipe } from "@wasp/entities";

    export const getRecipes: GetRecipes<{}, Recipe[]> = async (_args, context) => {
      return context.entities.Recipe.findMany( // Prisma query
        { where: { user: { id: context.user.id } } }
      );
    };

    export const addRecipe ...

    Now we can very easily use these in our React components!

    For the end, let's create a home page of our app.

    First we define it in main.wasp:

    main.wasp
    ...

    route HomeRoute { path: "/", to: HomePage }
    page HomePage {
      component: import { HomePage } from "@client/pages/HomePage",
      authRequired: true // Will send user to /login if not authenticated.
    }

    and then implement it as a React component in JS/TS (that calls the Operations we previously defined):

    src/client/pages/HomePage.tsx
    import getRecipes from "@wasp/queries/getRecipes";
    import { useQuery } from "@wasp/queries";
    import type { User } from "@wasp/entities";

    export function HomePage({ user }: { user: User }) {
      // Due to full-stack type safety, `recipes` will be of type `Recipe[]` here.
      const { data: recipes, isLoading } = useQuery(getRecipes); // Calling our query here!

      if (isLoading) {
        return <div>Loading...</div>;
      }

      return (
        <div>
          <h1>Recipes</h1>
          <ul>
            {recipes ? recipes.map((recipe) => (
              <li key={recipe.id}>
                <div>{recipe.title}</div>
                <div>{recipe.description}</div>
              </li>
            )) : 'No recipes defined yet!'}
          </ul>
        </div>
      );
    }

    And voila! We are listing all the recipes in our app 🎉

    This was just a quick example to give you a taste of what Wasp is. For step by step tour through the most important Wasp features, check out the Todo app tutorial.

    note

    Above we skipped defining /login and /signup pages to keep the example a bit shorter, but those are very simple to do by using Wasp's Auth UI feature.

    When to use Wasp​

    Wasp is addressing the same core problems that typical web app frameworks are addressing, and it in big part looks, swims and quacks like a web app framework.

    Best used for​

    • building full-stack web apps (like e.g. Airbnb or Asana)
    • quickly starting a web app with industry best practices
    • to be used alongside modern web dev stack (currently supported React and Node)

    Avoid using Wasp for​

    • building static/presentational websites
    • to be used as a no-code solution
    • to be a solve-it-all tool in a single language

    Wasp is a DSL​

    note

    You don't need to know what a DSL is to use Wasp, but if you are curious, you can read more about it below.

    Wasp does not match typical expectations of a web app framework: it is not a set of libraries, it is instead a programming language that understands your code and can do a lot of things for you.

    Wasp is a programming language, but a specific kind: it is specialized for a single purpose: building modern web applications. We call such languages DSLs (Domain Specific Language).

    Other examples of DSLs that are often used today are e.g. SQL for databases and HTML for web page layouts. The main advantage and reason why DSLs exist is that they need to do only one task (e.g. database queries) so they can do it well and provide the best possible experience for the developer.

    The same idea stands behind Wasp - a language that will allow developers to build modern web applications with 10x less code and less stack-specific knowledge.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/advanced/apis.html b/docs/0.11.8/advanced/apis.html index e48c9ff05e..6bec815c17 100644 --- a/docs/0.11.8/advanced/apis.html +++ b/docs/0.11.8/advanced/apis.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.11.8

    Custom HTTP API Endpoints

    In Wasp, the default client-server interaction mechanism is through Operations. However, if you need a specific URL method/path, or a specific response, Operations may not be suitable for you. For these cases, you can use an api. Best of all, they should look and feel very familiar.

    How to Create an API​

    APIs are used to tie a JS function to a certain endpoint e.g. POST /something/special. They are distinct from Operations and have no client-side helpers (like useQuery).

    To create a Wasp API, you must:

    1. Declare the API in Wasp using the api declaration
    2. Define the API's NodeJS implementation

    After completing these two steps, you'll be able to call the API from the client code (via our Axios wrapper), or from the outside world.

    Declaring the API in Wasp​

    First, we need to declare the API in the Wasp file and you can easily do this with the api declaration:

    main.wasp
    // ...

    api fooBar { // APIs and their implementations don't need to (but can) have the same name.
      fn: import { fooBar } from "@server/apis.js",
      httpRoute: (GET, "/foo/bar")
    }

    Read more about the supported fields in the API Reference.

    Defining the API's NodeJS Implementation​

    After you defined the API, it should be implemented as a NodeJS function that takes three arguments:

    1. req: Express Request object
    2. res: Express Response object
    3. context: An additional context object injected into the API by Wasp. This object contains user session information, as well as information about entities. The examples here won't use the context for simplicity purposes. You can read more about it in the section about using entities in APIs.
    src/server/apis.js
    export const fooBar = (req, res, context) => {
      res.set("Access-Control-Allow-Origin", "*"); // Example of modifying headers to override Wasp default CORS middleware.
      res.json({ msg: `Hello, ${context.user?.username || "stranger"}!` });
    };

    Using the API​

    Using the API externally​

    To use the API externally, you simply call the endpoint using the method and path you used.

    For example, if your app is running at https://example.com then from the above you could issue a GET to https://example/com/foo/callback (in your browser, Postman, curl, another web service, etc.).

    Using the API from the Client​

    To use the API from your client, including with auth support, you can import the Axios wrapper from @wasp/api and invoke a call. For example:

    src/client/pages/SomePage.jsx
    import React, { useEffect } from "react";
    import api from "@wasp/api";

    async function fetchCustomRoute() {
      const res = await api.get("/foo/bar");
      console.log(res.data);
    }

    export const Foo = () => {
      useEffect(() => {
        fetchCustomRoute();
      }, []);

      return <>// ...</>;
    };

    Making Sure CORS Works​

    APIs are designed to be as flexible as possible, hence they don't utilize the default middleware like Operations do. As a result, to use these APIs on the client side, you must ensure that CORS (Cross-Origin Resource Sharing) is enabled.

    You can do this by defining custom middleware for your APIs in the Wasp file.

    For example, an apiNamespace is a simple declaration used to apply some middlewareConfigFn to all APIs under some specific path:

    main.wasp
    apiNamespace fooBar {
      middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@server/apis.js",
      path: "/foo"
    }

    And then in the implementation file:

    src/server/apis.js
    export const apiMiddleware = (config) => {
      return config;
    };

    We are returning the default middleware which enables CORS for all APIs under the /foo path.

    For more information about middleware configuration, please see: Middleware Configuration

    Using Entities in APIs​

    In many cases, resources used in APIs will be Entities. To use an Entity in your API, add it to the api declaration in Wasp:

    main.wasp
    api fooBar {
      fn: import { fooBar } from "@server/apis.js",
      entities: [Task],
      httpRoute: (GET, "/foo/bar")
    }

    Wasp will inject the specified Entity into the APIs context argument, giving you access to the Entity's Prisma API:

    src/server/apis.js
    export const fooBar = (req, res, context) => {
      res.json({ count: await context.entities.Task.count() });
    };

    The object context.entities.Task exposes prisma.task from Prisma's CRUD API.

    API Reference​

    main.wasp
    api fooBar {
      fn: import { fooBar } from "@server/apis.js",
      httpRoute: (GET, "/foo/bar"),
      entities: [Task],
      auth: true,
      middlewareConfigFn: import { apiMiddleware } from "@server/apis.js"
    }

    The api declaration has the following fields:

    • fn: ServerImport required

      The import statement of the APIs NodeJs implementation.

    • httpRoute: (HttpMethod, string) required

      The HTTP (method, path) pair, where the method can be one of:

      • ALL, GET, POST, PUT or DELETE
      • and path is an Express path string.

    • entities: [Entity]

      A list of entities you wish to use inside your API. You can read more about it here.

    • auth: bool

      If auth is enabled, this will default to true and provide a context.user object. If you do not wish to attempt to parse the JWT in the Authorization Header, you should set this to false.

    • middlewareConfigFn: ServerImport

      The import statement to an Express middleware config function for this API. See more in middleware section of the docs.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/advanced/deployment/cli.html b/docs/0.11.8/advanced/deployment/cli.html index cc64cde4ee..f9e9c6b56b 100644 --- a/docs/0.11.8/advanced/deployment/cli.html +++ b/docs/0.11.8/advanced/deployment/cli.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.11.8

    Deploying with the Wasp CLI

    Wasp CLI can deploy your full-stack application with only a single command. The command automates the manual deployment process and is the recommended way of deploying Wasp apps.

    Supported Providers​

    Wasp supports automated deployment to the following providers:

    • Fly.io - they offer 5$ free credit each month
    • Railway (coming soon, track it here #1157)

    Fly.io​

    Prerequisites​

    Fly provides free allowances for up to 3 VMs (so deploying a Wasp app to a new account is free), but all plans require you to add your credit card information before you can proceed. If you don't, the deployment will fail.

    You can add the required credit card information on the account's billing page.

    Fly.io CLI

    You will need the flyctl CLI installed on your machine before you can deploy to Fly.io.

    Deploying​

    Using the Wasp CLI, you can easily deploy a new app to Fly.io with just a single command:

    wasp deploy fly launch my-wasp-app mia

    Please do not CTRL-C or exit your terminal while the commands are running.

    Under the covers, this runs the equivalent of the following commands:

    wasp deploy fly setup my-wasp-app mia
    wasp deploy fly create-db mia
    wasp deploy fly deploy

    The commands above use the app basename my-wasp-app and deploy it to the Miami, Florida (US) region (called mia). Read more about Fly.io regions here.

    Unique Name

    Your app name must be unique across all of Fly or deployment will fail.

    The basename is used to create all three app tiers, resulting in three separate apps in your Fly dashboard:

    • my-wasp-app-client
    • my-wasp-app-server
    • my-wasp-app-db

    You'll notice that Wasp creates two new files in your project root directory:

    • fly-server.toml
    • fly-client.toml

    You should include these files in your version control so that you can deploy your app with a single command in the future.

    Using a Custom Domain For Your App​

    Setting up a custom domain is a three-step process:

    1. You need to add your domain to your Fly client app. You can do this by running:
    wasp deploy fly cmd --context client certs create mycoolapp.com
    Use Your Domain

    Make sure to replace mycoolapp.com with your domain in all of the commands mentioned in this section.

    This command will output the instructions to add the DNS records to your domain. It will look something like this:

    You can direct traffic to mycoolapp.com by:

    1: Adding an A record to your DNS service which reads

        A @ 66.241.1XX.154

    You can validate your ownership of mycoolapp.com by:

    2: Adding an AAAA record to your DNS service which reads:

        AAAA @ 2a09:82XX:1::1:ff40

    1. You need to add the DNS records for your domain:

      This will depend on your domain provider, but it should be a matter of adding an A record for @ and an AAAA record for @ with the values provided by the previous command.

    2. You need to set your domain as the WASP_WEB_CLIENT_URL environment variable for your server app:

    wasp deploy fly cmd --context server secrets set WASP_WEB_CLIENT_URL=https://mycoolapp.com

    We need to do this to keep our CORS configuration up to date.

    That's it, your app should be available at https://mycoolapp.com! 🎉

    API Reference​

    launch​

    launch is a convenience command that runs setup, create-db, and deploy in sequence.

    wasp deploy fly launch <app-name> <region>

    It accepts the following arguments:

    • <app-name> - the name of your app required

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    It gives you the same result as running the following commands:

    wasp deploy fly setup <app-name> <region>
    wasp deploy fly create-db <region>
    wasp deploy fly deploy

    Environment Variables​

    If you are deploying an app that requires any other environment variables (like social auth secrets), you can set them with the --server-secret option:

    wasp deploy fly launch my-wasp-app mia --server-secret GOOGLE_CLIENT_ID=<...> --server-secret GOOGLE_CLIENT_SECRET=<...>

    setup​

    setup will create your client and server apps on Fly, and add some secrets, but does not deploy them.

    wasp deploy fly setup <app-name> <region>

    It accepts the following arguments:

    • <app-name> - the name of your app required

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    After running setup, Wasp creates two new files in your project root directory: fly-server.toml and fly-client.toml. You should include these files in your version control.

    You can edit the fly-server.toml and fly-client.toml files to further configure your Fly deployments. Wasp will use the TOML files when you run deploy.

    If you want to maintain multiple apps, you can add the --fly-toml-dir <abs-path> option to point to different directories, like "dev" or "staging".

    Execute Only Once

    You should only run setup once per app. If you run it multiple times, it will create unnecessary apps on Fly.

    create-db​

    create-db will create a new database for your app.

    wasp deploy fly create-db <region>

    It accepts the following arguments:

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    Execute Only Once

    You should only run create-db once per app. If you run it multiple times, it will create multiple databases, but your app needs only one.

    deploy​

    wasp deploy fly deploy

    deploy pushes your client and server live.

    Run this command whenever you want to update your deployed app with the latest changes:

    wasp deploy fly deploy

    cmd​

    If want to run arbitrary Fly commands (e.g. flyctl secrets list for your server app), here's how to do it:

    wasp deploy fly cmd secrets list --context server

    Fly.io Regions​

    Fly.io runs applications physically close to users: in datacenters around the world, on servers we run ourselves. You can currently deploy your apps in 34 regions, connected to a global Anycast network that makes sure your users hit our nearest server, whether they’re in Tokyo, São Paolo, or Frankfurt.

    Read more on Fly regions here.

    You can find the list of all available Fly regions by running:

    flyctl platform regions

    Environment Variables​

    If you are deploying an app that requires any other environment variables (like social auth secrets), you can set them with the secrets set command:

    wasp deploy fly cmd secrets set GOOGLE_CLIENT_ID=<...> GOOGLE_CLIENT_SECRET=<...> --context=server

    Mutliple Fly Organizations​

    If you have multiple organizations, you can specify a --org option. For example:

    wasp deploy fly launch my-wasp-app mia --org hive

    Building Locally​

    Fly.io offers support for both locally built Docker containers and remotely built ones. However, for simplicity and reproducibility, the CLI defaults to the use of a remote Fly.io builder.

    If you want to build locally, supply the --build-locally option to wasp deploy fly launch or wasp deploy fly deploy.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/advanced/deployment/manually.html b/docs/0.11.8/advanced/deployment/manually.html index f48c0e543a..d12d613118 100644 --- a/docs/0.11.8/advanced/deployment/manually.html +++ b/docs/0.11.8/advanced/deployment/manually.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -31,7 +31,7 @@ Set it to a random string at least 32 characters long (you can 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 set the necessary environment variables.

    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 set the DATABASE_URL env var correctly 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​

    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 set the necessary environment variables.

    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​

    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​

    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 set the necessary environment variables.

    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​

    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.11.8/advanced/deployment/overview.html b/docs/0.11.8/advanced/deployment/overview.html index df930d5e20..80b1358859 100644 --- a/docs/0.11.8/advanced/deployment/overview.html +++ b/docs/0.11.8/advanced/deployment/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ 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.11.8/advanced/email.html b/docs/0.11.8/advanced/email.html index d89a41a8c0..f366065d3f 100644 --- a/docs/0.11.8/advanced/email.html +++ b/docs/0.11.8/advanced/email.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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:

    • 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​

    Sending emails while developing

    When you run your app in development mode, the emails are not sent. Instead, they are logged to the console.

    To enable sending emails in development mode, you need to set the SEND_EMAILS_IN_DEVELOPMENT env variable to true in your .env.server file.

    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/email module and call the send method on it.

    src/actions/sendEmail.js
    import { emailSender } from "@wasp/email/index.js";

    // 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​

    For each provider, you'll need to set up env variables in the .env.server file at the root of your project.

    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 SMTP, Mailgun or SendGrid.

    • 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/email/index.js";

    // 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.11.8/advanced/jobs.html b/docs/0.11.8/advanced/jobs.html index 4651921547..a131a77914 100644 --- a/docs/0.11.8/advanced/jobs.html +++ b/docs/0.11.8/advanced/jobs.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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 "@server/workers/bar.js"
        },
        entities: [Task],
      }

    2. After declaring the Job, implement its worker function:

      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/jobs/mySpecialJob.js'

      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 "@server/workers/bar.js"
      },
      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 "@server/workers/bar.js",
        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: ServerImport required

        • An async function that performs the work. Since Wasp executes Jobs on the server, you must import it from @server.
        • 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:

        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/jobs/mySpecialJob.js'

    • 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.
      • For pg-boss, you can import a Symbol from: import { PG_BOSS_EXECUTOR_NAME } from '@wasp/jobs/core/pgBoss/pgBossJob.js' if you wish to compare against executorName.

    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.11.8/advanced/links.html b/docs/0.11.8/advanced/links.html index dc4971bc88..35c496900a 100644 --- a/docs/0.11.8/advanced/links.html +++ b/docs/0.11.8/advanced/links.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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/router:

    TaskList.tsx
    import { Link } from '@wasp/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/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/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.11.8/advanced/middleware-config.html b/docs/0.11.8/advanced/middleware-config.html index d0563202b8..0daaefaa85 100644 --- a/docs/0.11.8/advanced/middleware-config.html +++ b/docs/0.11.8/advanced/middleware-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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 "@server/serverSetup.js",
        middlewareConfigFn: import { serverMiddlewareFn } from "@server/serverSetup.js"
      },
    }
    src/server/serverSetup.js
    import cors from 'cors'
    import config from '@wasp/config.js'

    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 "@server/apis.js",
      middlewareConfigFn: import { webhookCallbackMiddlewareFn } from "@server/apis.js",
      httpRoute: (POST, "/webhook/callback"),
      auth: false
    }
    src/server/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 "@server/apis.js",
      path: "/foo/bar"
    }
    src/server/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.11.8/advanced/web-sockets.html b/docs/0.11.8/advanced/web-sockets.html index a314826896..a1b7496c0f 100644 --- a/docs/0.11.8/advanced/web-sockets.html +++ b/docs/0.11.8/advanced/web-sockets.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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 "@server/webSocket.js",
        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/server/webSocket.js
    import { v4 as uuidv4 } from 'uuid'

    export const webSocketFn = (io, context) => {
      io.on('connection', (socket) => {
        const username = socket.data.user?.email || socket.data.user?.username || '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/client/ChatPage.jsx
    import React, { useState } from 'react'
    import {
      useSocket,
      useSocketListener,
    } from '@wasp/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 "@server/webSocket.js",
        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.11.8/auth/email.html b/docs/0.11.8/auth/email.html index 2a0bc1d734..3a67fe077d 100644 --- a/docs/0.11.8/auth/email.html +++ b/docs/0.11.8/auth/email.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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 email auth and social auth together

    If a user signs up with Google or Github (and you set it up to save their social provider e-mail info on the User entity), they'll be able to reset their password and login with e-mail and password ✅

    If a user signs up with the e-mail and password and then tries to login with a social provider (Google or Github), they won't be able to do that ❌

    In the future, we will lift this limitation and enable smarter merging of accounts.

    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 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,
            },
            allowUnverifiedLogin: false,
          },
        },
        onAuthFailedRedirectTo: "/login",
        onAuthSucceededRedirectTo: "/"
      },
    }

    Read more about the email auth method options here.

    2. Add the User Entity​

    When email authentication is enabled, Wasp expects certain fields in your userEntity. Let's add these fields to our main.wasp file:

    main.wasp
    // 5. Define the user entity
    entity User {=psl
        id                        Int           @id @default(autoincrement())
        email                     String?       @unique
        password                  String?
        isEmailVerified           Boolean       @default(false)
        emailVerificationSentAt   DateTime?
        passwordResetSentAt       DateTime?
        // Add your own fields below
        // ...
    psl=}

    Read more about the userEntity fields here.

    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 "@client/pages/auth.jsx"
    }

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { Signup } from "@client/pages/auth.jsx"
    }

    route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
    page RequestPasswordResetPage {
      component: import { RequestPasswordReset } from "@client/pages/auth.jsx",
    }

    route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
    page PasswordResetPage {
      component: import { PasswordReset } from "@client/pages/auth.jsx",
    }

    route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
    page EmailVerificationPage {
      component: import { EmailVerification } from "@client/pages/auth.jsx",
    }

    We'll define the React components for these pages in the client/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 client/pages folder and add the following to it:

    client/pages/auth.jsx
    import { LoginForm } from "@wasp/auth/forms/Login";
    import { SignupForm } from "@wasp/auth/forms/Signup";
    import { VerifyEmailForm } from "@wasp/auth/forms/VerifyEmail";
    import { ForgotPasswordForm } from "@wasp/auth/forms/ForgotPassword";
    import { ResetPasswordForm } from "@wasp/auth/forms/ResetPassword";
    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 SendGrid in this guide to send our e-mails. You can use any of the supported email providers.

    To set up SendGrid to send emails, we will add the following to our main.wasp file:

    main.wasp
    app myApp {
      // ...
      // 7. Set up the email sender
      emailSender: {
        provider: SendGrid,
      }
    }

    ... and add the following to our .env.server file:

    .env.server
    SENDGRID_API_KEY=<your key>

    If you are not sure how to get a SendGrid API key, read more here.

    Read more about setting up email senders in the sending emails docs.

    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 using auth docs.

    Login and Signup Flows​

    Login​

    Auth UI

    If logging in with an unverified email is allowed, the user will be able to login with an unverified email address. If logging in with an unverified email is not allowed, the user will be shown an error message.

    Read more about the allowUnverifiedLogin option here.

    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 using auth docs.

    Email Verification Flow​

    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.

    Using The 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 using auth docs.

    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"
      },
      // ...
    }

    // Using email auth requires the `userEntity` to have at least the following fields
    entity User {=psl
        id                        Int           @id @default(autoincrement())
        email                     String?       @unique
        password                  String?
        isEmailVerified           Boolean       @default(false)
        emailVerificationSentAt   DateTime?
        passwordResetSentAt       DateTime?
    psl=}

    Email auth requires that userEntity specified in auth contains:

    • optional email field of type String
    • optional password field of type String
    • isEmailVerified field of type Boolean with a default value of false
    • optional emailVerificationSentAt field of type DateTime
    • optional passwordResetSentAt field of type DateTime

    Fields in the email dict​

    main.wasp
    app myApp {
      title: "My app",
      // ...

      auth: {
        userEntity: User,
        methods: {
          email: {
            fromField: {
              name: "My App",
              email: "hello@itsme.com"
            },
            emailVerification: {
              clientRoute: EmailVerificationRoute,
              getEmailContentFn: import { getVerificationEmailContent } from "@server/auth/email.js",
            },
            passwordReset: {
              clientRoute: PasswordResetRoute,
              getEmailContentFn: import { getPasswordResetEmailContent } from "@server/auth/email.js",
            },
            allowUnverifiedLogin: false,
          },
        },
        onAuthFailedRedirectTo: "/someRoute"
      },
      // ...
    }

    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/auth/email/actions';
      ...
      await verifyEmail({ token });
      note

      We used Auth UI above to avoid doing this work of sending the token to the server manually.

    • getEmailContentFn: ServerImport: 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 server directory.

      server/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/auth/email/actions';
      ...
      await requestPasswordReset({ email });
      src/pages/PasswordResetPage.jsx
      import { resetPassword } from '@wasp/auth/email/actions';
      ...
      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: ServerImport: 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:

      server/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.

    allowUnverifiedLogin: bool: specifies whether the user can login without verifying their e-mail address​

    It defaults to false. If allowUnverifiedLogin is set to true, the user can login without verifying their e-mail address, otherwise users will receive a 401 error when trying to login without verifying their e-mail address.

    Sometimes you want to allow unverified users to login to provide them a different onboarding experience. Some of the pages can be viewed without verifying the e-mail address, but some of them can't. You can use the isEmailVerified field on the user entity to check if the user has verified their e-mail address.

    If you have any questions, feel free to ask them on our Discord server.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/auth/overview.html b/docs/0.11.8/auth/overview.html index 0d29f89ce5..0dbc307be4 100644 --- a/docs/0.11.8/auth/overview.html +++ b/docs/0.11.8/auth/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ For update(), they only run when the field mentioned in validates is present.

    The validation process stops on the first validator to return false. If enabled, default validations run first and then custom validations.

    Validation Error Handling​

    When creating, updating, or deleting entities, you may wish to handle validation errors. Wasp exposes a class called AuthError for this purpose.

    src/server/actions.js
    try {
      await context.entities.User.update(...)
    } catch (e) {
      if (e instanceof AuthError) {
        throw new HttpError(422, 'Validation failed', { message: e.message })
      } else {
        throw e
      }
    }

    Customizing the Signup Process​

    Sometimes you want to include extra fields in your signup process, like first name and last name.

    In Wasp, in this case:

    • you need to define the fields that you want saved in the database,
    • you need to customize the SignupForm.

    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.signup.additionalFields field in our main.wasp file:

    main.wasp
    app crudTesting {
      // ...
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login",
        signup: {
          additionalFields: import { fields } from "@server/auth/signup.js",
        },
      },
    }

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

    Then we'll define and export the fields object from the server/auth/signup.js file:

    server/auth/signup.js
    import { defineAdditionalSignupFields } from '@wasp/auth/index.js'

    export const fields = defineAdditionalSignupFields({
      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 fields 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
    server/auth/signup.js
    import { defineAdditionalSignupFields } from '@wasp/auth/index.js'
    import * as z from 'zod'

    export const fields = defineAdditionalSignupFields({
      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.
    client/SignupPage.jsx
    import { SignupForm } from '@wasp/auth/forms/Signup'
    import {
      FormError,
      FormInput,
      FormItemGroup,
      FormLabel,
    } from '@wasp/auth/forms/internal/Form'

    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.

    client/SignupPage.jsx
    import { SignupForm } from '@wasp/auth/forms/Signup'
    import { FormItemGroup } from '@wasp/auth/forms/internal/Form'

    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,
        externalAuthEntity: SocialLogin,
        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. Its mandatory fields depend on your chosen auth method.

    externalAuthEntity: entity​

    Wasp requires you to set the field auth.externalAuthEntity for all authentication methods relying on an external authorizatino provider (e.g., Google). You also need to tweak the Entity referenced by auth.userEntity, as shown below.

    main.wasp
    //...
      auth: {
        userEntity: User,
        externalAuthEntity: SocialLogin,
    //...

    entity User {=psl
        id                        Int           @id @default(autoincrement())
        //...
        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=}
    note

    The same externalAuthEntity can be used across different social login providers (e.g., both GitHub and Google can use the same entity).

    See Google docs and GitHub docs for more details.

    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

    Discord »

    Users sign in with their Discord 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.signup.additionalFields field in your main.wasp file.

    main.wasp
    app crudTesting {
      // ...
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login",
        signup: {
          additionalFields: import { fields } from "@server/auth/signup.js",
        },
      },
    }

    Then we'll export the fields object from the server/auth/signup.js file:

    server/auth/signup.js
    import { defineAdditionalSignupFields } from '@wasp/auth/index.js'

    export const fields = defineAdditionalSignupFields({
      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 fields object is an object where the keys represent the field name, and the values are functions which receive the data sent from the client* and return the value of the field.

    If the field value 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.

    client/SignupPage.jsx
    import { SignupForm } from '@wasp/auth/forms/Signup'
    import {
      FormError,
      FormInput,
      FormItemGroup,
      FormLabel,
    } from '@wasp/auth/forms/internal/Form'

    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.11.8/auth/social-auth/github.html b/docs/0.11.8/auth/social-auth/github.html index 57f3748c2e..8e6e7d9130 100644 --- a/docs/0.11.8/auth/social-auth/github.html +++ b/docs/0.11.8/auth/social-auth/github.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ 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,
        externalAuthEntity: SocialLogin,
        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.

    Also, if the userEntity has:

    • A username field: Wasp sets it to a random username (e.g. nice-blue-horse-14357).
    • A password field: Wasp sets it to a random string.

    This is a historical coupling between auth methods we plan to remove in the future.

    Overrides​

    Wasp lets you override the default behavior. You can create custom setups, such as allowing users to define a custom username rather instead of getting a randomly generated one.

    There are two mechanisms (functions) used for overriding the default behavior:

    • getUserFieldsFn
    • 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 getUserFieldsFn function.

    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 functions in action:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.11.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        externalAuthEntity: SocialLogin,
        methods: {
          gitHub: {
            configFn: import { getConfig } from "@server/auth/github.js",
            getUserFieldsFn: import { getUserFields } from "@server/auth/github.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    entity User {=psl
        id                        Int     @id @default(autoincrement())
        username                  String  @unique
        displayName               String
        externalAuthAssociations  SocialLogin[]
    psl=}

    // ...
    src/server/auth/github.js
    import { generateAvailableDictionaryUsername } from "@wasp/core/auth.js";

    export const getUserFields = async (_context, args) => {
      const username = await generateAvailableDictionaryUsername();
      const displayName = args.profile.displayName;
      return { username, 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
    • getUserFieldsFn

    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,
        externalAuthEntity: SocialLogin,
        methods: {
          gitHub: {
            configFn: import { getConfig } from "@server/auth/github.js",
            getUserFieldsFn: import { getUserFields } from "@server/auth/github.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    The gitHub dict has the following properties:

    • configFn: ServerImport​

      This function should return an object with the Client ID, Client Secret, and scope for the OAuth provider.

      src/server/auth/github.js
      export function getConfig() {
        return {
          clientID, // look up from env or elsewhere
          clientSecret, // look up from env or elsewhere
          scope: [],
        }
      }

    • getUserFieldsFn: ServerImport​

      This function should return the user fields to use when creating a new user.

      The context contains the User entity, and the args object contains GitHub profile information. You can do whatever you want with this information (e.g., generate a username).

      Here is how you could generate a username based on the Github display name:

      src/server/auth/github.js
      import { generateAvailableUsername } from '@wasp/core/auth.js'

      export const getUserFields = async (_context, args) => {
        const username = await generateAvailableUsername(
          args.profile.displayName.split(' '),
          { separator: '.' }
        )
        return { username }
      }

      Wasp exposes two functions that can help you generate usernames. Import them from @wasp/core/auth.js:

      • generateAvailableUsername takes an array of strings and an optional separator and generates a string ending with a random number that is not yet in the database. For example, the above could produce something like "Jim.Smith.3984" for a Github user Jim Smith.
      • generateAvailableDictionaryUsername generates a random dictionary phrase that is not yet in the database. For example, nice-blue-horse-27160.
    - - + + \ No newline at end of file diff --git a/docs/0.11.8/auth/social-auth/google.html b/docs/0.11.8/auth/social-auth/google.html index 0838b39ace..596eea4d0e 100644 --- a/docs/0.11.8/auth/social-auth/google.html +++ b/docs/0.11.8/auth/social-auth/google.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -30,7 +30,7 @@ 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,
        externalAuthEntity: SocialLogin,
        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.

    Also, if the userEntity has:

    • A username field: Wasp sets it to a random username (e.g. nice-blue-horse-14357).
    • A password field: Wasp sets it to a random string.

    This is a historical coupling between auth methods we plan to remove in the future.

    Overrides​

    Wasp lets you override the default behavior. You can create custom setups, such as allowing users to define a custom username rather instead of getting a randomly generated one.

    There are two mechanisms (functions) used for overriding the default behavior:

    • getUserFieldsFn
    • 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 getUserFieldsFn function.

    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 functions in action:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.11.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        externalAuthEntity: SocialLogin,
        methods: {
          google: {
            configFn: import { getConfig } from "@server/auth/google.js",
            getUserFieldsFn: import { getUserFields } from "@server/auth/google.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    entity User {=psl
        id                        Int     @id @default(autoincrement())
        username                  String  @unique
        displayName               String
        externalAuthAssociations  SocialLogin[]
    psl=}

    // ...
    src/server/auth/google.js
    import { generateAvailableDictionaryUsername } from '@wasp/core/auth.js'

    export const getUserFields = async (_context, args) => {
      const username = await generateAvailableDictionaryUsername()
      const displayName = args.profile.displayName
      return { username, 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
    • getUserFieldsFn

    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,
        externalAuthEntity: SocialLogin,
        methods: {
          google: {
            configFn: import { getConfig } from "@server/auth/google.js",
            getUserFieldsFn: import { getUserFields } from "@server/auth/google.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    The google dict has the following properties:

    • configFn: ServerImport​

      This function must return an object with the Client ID, the Client Secret, and the scope for the OAuth provider.

      src/server/auth/google.js
      export function getConfig() {
        return {
          clientID, // look up from env or elsewhere
          clientSecret, // look up from env or elsewhere
          scope: ['profile', 'email'],
        }
      }

    • getUserFieldsFn: ServerImport​

      This function must return the user fields to use when creating a new user.

      The context contains the User entity, and the args object contains Google profile information. You can do whatever you want with this information (e.g., generate a username).

      Here is how to generate a username based on the Google display name:

      src/server/auth/google.js
      import { generateAvailableUsername } from '@wasp/core/auth.js'

      export const getUserFields = async (_context, args) => {
        const username = await generateAvailableUsername(
          args.profile.displayName.split(' '),
          { separator: '.' }
        )
        return { username }
      }

      Wasp exposes two functions that can help you generate usernames. Import them from @wasp/core/auth.js:

      • generateAvailableUsername takes an array of strings and an optional separator and generates a string ending with a random number that is not yet in the database. For example, the above could produce something like "Jim.Smith.3984" for a Github user Jim Smith.
      • generateAvailableDictionaryUsername generates a random dictionary phrase that is not yet in the database. For example, nice-blue-horse-27160.
    - - + + \ No newline at end of file diff --git a/docs/0.11.8/auth/social-auth/overview.html b/docs/0.11.8/auth/social-auth/overview.html index 90b0a7c740..b46dbbbd69 100644 --- a/docs/0.11.8/auth/social-auth/overview.html +++ b/docs/0.11.8/auth/social-auth/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -34,7 +34,7 @@ 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.

    client/LoginPage.jsx
    import {
      SignInButton as GoogleSignInButton,
      signInUrl as googleSignInUrl,
    } from '@wasp/auth/helpers/Google'
    import {
      SignInButton as GitHubSignInButton,
      signInUrl as gitHubSignInUrl,
    } from '@wasp/auth/helpers/GitHub'

    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
    • getUserFields and configFn functions

    Check the provider-specific API References:

    The externalAuthEntity and Its Fields​

    Using social login providers requires you to define an External Auth Entity and declare it with the app.auth.externalAuthEntity field. This Entity holds the data relevant to the social provider. All social providers share the same Entity.

    main.wasp
    // ...

    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=}

    // ...
    info

    You don't need to know these details, you can just copy and paste the entity definition above and you are good to go.

    The Entity acting as app.auth.externalAuthEntity must include the following fields:

    • provider - The provider's name (e.g. google, github, etc.).
    • providerId - The user's ID on the provider's platform.
    • userId - The user's ID on your platform (this references the id field from the Entity acting as app.auth.userEntity).
    • user - A relation to the userEntity (see the userEntity section) for more details.
    • createdAt - A timestamp of when the association was created.
    • @@unique([provider, providerId, userId]) - A unique constraint on the combination of provider, providerId and userId.

    Expected Fields on the userEntity​

    Using Social login providers requires you to add one extra field to the Entity acting as app.auth.userEntity:

    main.wasp
    // ...

    entity User {=psl
        id                        Int           @id @default(autoincrement())
        //...
        externalAuthAssociations  SocialLogin[]
    psl=}

    // ...
    - - + + \ No newline at end of file diff --git a/docs/0.11.8/auth/ui.html b/docs/0.11.8/auth/ui.html index 245c9a7389..e23b27706d 100644 --- a/docs/0.11.8/auth/ui.html +++ b/docs/0.11.8/auth/ui.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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 "@client/LoginPage.jsx"
    }
    client/LoginPage.jsx
    import { LoginForm } from '@wasp/auth/forms/Login'

    // 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 "@client/SignupPage.jsx"
    }
    client/SignupPage.jsx
    import { SignupForm } from '@wasp/auth/forms/Signup'

    // 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 Using Auth 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 "@client/ForgotPasswordPage.jsx"
    }
    client/ForgotPasswordPage.jsx
    import { ForgotPasswordForm } from '@wasp/auth/forms/ForgotPassword'

    // 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 "@client/ResetPasswordPage.jsx"
    }
    client/ResetPasswordPage.jsx
    import { ResetPasswordForm } from '@wasp/auth/forms/ResetPassword'

    // 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 "@client/VerifyEmailPage.jsx"
    }
    client/VerifyEmailPage.jsx
    import { VerifyEmailForm } from '@wasp/auth/forms/VerifyEmail'

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

    client/appearance.js
    export const authAppearance = {
      colors: {
        brand: '#5969b8', // blue
        brandAccent: '#de5998', // pink
        submitButtonText: 'white',
      },
    }
    client/LoginPage.jsx
    import { LoginForm } from '@wasp/auth/forms/Login'
    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.

    client/LoginPage.jsx
    import { LoginForm } from '@wasp/auth/forms/Login'
    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:

    client/LoginPage.jsx
    import { LoginForm } from '@wasp/auth/forms/Login'

    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:

    client/appearance.js
    export const appearance = {
      colors: {
        brand: '#5969b8', // blue
        brandAccent: '#de5998', // pink
        submitButtonText: 'white',
      },
    }
    client/LoginPage.jsx
    import { LoginForm } from '@wasp/auth/forms/Login'

    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.11.8/auth/username-and-pass.html b/docs/0.11.8/auth/username-and-pass.html index 795bcfdbd3..40d6453256 100644 --- a/docs/0.11.8/auth/username-and-pass.html +++ b/docs/0.11.8/auth/username-and-pass.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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 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​

    When username authentication is enabled, Wasp expects certain fields in your userEntity. Let's add these fields to our main.wasp file:

    main.wasp
    // 3. Define the user entity
    entity User {=psl
        id                        Int           @id @default(autoincrement())
        username                  String        @unique
        password                  String
        // Add your own fields below
        // ...
    psl=}

    Read more about the userEntity fields here.

    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 "@client/pages/auth.jsx"
    }
    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { Signup } from "@client/pages/auth.jsx"
    }

    We'll define the React components for these pages in the client/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 client/pages folder and add the following to it:

    client/pages/auth.jsx
    import { LoginForm } from "@wasp/auth/forms/Login";
    import { SignupForm } from "@wasp/auth/forms/Signup";
    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 using auth docs.

    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 and how to override them in the using auth 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 and login actions which uses the Prisma client, 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:

    client/pages/auth.jsx
    // Importing the login action 👇
    import login from '@wasp/auth/login'

    import { useState } from 'react'
    import { useHistory } from 'react-router-dom'
    import { 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

      Wasp only stores the auth-related fields of the user entity. Adding extra fields to userFields will not have any effect.

      If you need to add extra fields to the user entity, we suggest doing it in a separate step after the user logs in for the first time.

    You can use it like this:

    client/pages/auth.jsx
    // Importing the signup and login actions 👇
    import signup from '@wasp/auth/signup'
    import login from '@wasp/auth/login'

    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 actions​

    The code of your custom sign-up action can look like this:

    main.wasp
    // ...

    action signupUser {
      fn: import { signUp } from "@server/auth/signup.js",
      entities: [User]
    }
    src/server/auth/signup.js
    export const signUp = async (args, context) => {
      // Your custom code before sign-up.
      // ...

      const newUser = context.entities.User.create({
        data: {
          username: args.username,
          password: args.password // password hashed automatically by Wasp! 🐝
        }
      })

      // Your custom code after sign-up.
      // ...
      return newUser
    }

    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 using auth docs.

    API Reference​

    userEntity fields​

    main.wasp
    app myApp {
      wasp: {
        version: "^0.11.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login"
      }
    }

    // Wasp requires the `userEntity` to have at least the following fields
    entity User {=psl
        id                        Int           @id @default(autoincrement())
        username                  String        @unique
        password                  String
    psl=}

    Username & password auth requires that userEntity specified in auth contains:

    • username field of type String
    • password field of type String

    Fields in the usernameAndPassword dict​

    main.wasp
    app myApp {
      wasp: {
        version: "^0.11.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login"
      }
    }
    // ...
    info

    usernameAndPassword dict doesn't have any options at the moment.

    You can read about the rest of the auth options in the using auth section of the docs.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/contact.html b/docs/0.11.8/contact.html index 5f700b1a06..513c31f72b 100644 --- a/docs/0.11.8/contact.html +++ b/docs/0.11.8/contact.html @@ -18,14 +18,14 @@ - - - + + +
    - - + + \ No newline at end of file diff --git a/docs/0.11.8/contributing.html b/docs/0.11.8/contributing.html index f449178251..3184cccfdd 100644 --- a/docs/0.11.8/contributing.html +++ b/docs/0.11.8/contributing.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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.11.8/data-model/backends.html b/docs/0.11.8/data-model/backends.html index 34ba2ecfcd..25f65e4385 100644 --- a/docs/0.11.8/data-model/backends.html +++ b/docs/0.11.8/data-model/backends.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -36,7 +36,7 @@ Whenever you modify the db.system field, make sure to run wasp db migrate-dev to apply the changes.

  • seeds: [ServerImport]

    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 "@server/dbSeeds.js",
          ]
        }
      }

      Use the following command:

      wasp db seed devSeedSimple
    - - + + \ No newline at end of file diff --git a/docs/0.11.8/data-model/crud.html b/docs/0.11.8/data-model/crud.html index 59fb4f0a65..7189b51d22 100644 --- a/docs/0.11.8/data-model/crud.html +++ b/docs/0.11.8/data-model/crud.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.11.8

    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 "@server/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())
      username String @unique
      password String
      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 "@client/MainPage.jsx",
      authRequired: true,
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@client/LoginPage.jsx",
    }

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@client/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 "@server/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 @server/tasks.js will be used.

    Our Custom create Operation​

    Here's the src/server/tasks.ts file:

    src/server/tasks.js
    import HttpError from '@wasp/core/HttpError.js'

    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:

    pages/MainPage.jsx
    import { Tasks } from '@wasp/crud/Tasks'
    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/client/LoginPage.jsx
    import { LoginForm } from '@wasp/auth/forms/Login'
    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/client/SignupPage.jsx
    import { SignupForm } from '@wasp/auth/forms/Signup'

    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 "@server/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: ServerImport - 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/crud/{crud name}. The names of the imports are the same as the names of the operations. For example, if you have a CRUD called Tasks, you would import the operations like this:

    SomePage.jsx
    import { Tasks } from '@wasp/crud/Tasks'

    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.11.8/data-model/entities.html b/docs/0.11.8/data-model/entities.html index 1bc851538e..f31dae8c8c 100644 --- a/docs/0.11.8/data-model/entities.html +++ b/docs/0.11.8/data-model/entities.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.11.8

    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 prismaClient from '@wasp/dbClient'`

    prismaClient.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.11.8/data-model/operations/actions.html b/docs/0.11.8/data-model/operations/actions.html index 32a3fb5f4e..e9e2cbdfc6 100644 --- a/docs/0.11.8/data-model/operations/actions.html +++ b/docs/0.11.8/data-model/operations/actions.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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 "@server/actions.js"
        entities: [Foo]
    }

    Expects to find a named export createfoo from the file src/server/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/client/pages/Task.jsx
    import React from 'react'
    import { useQuery } from '@wasp/queries'
    import { useAction } from '@wasp/actions'
    import getTask from '@wasp/queries/getTask'
    import markTaskAsDone from '@wasp/actions/markTaskAsDone'

    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/queries/getTasks'

    const queryKey = getTasks.queryCacheKey
    - - + + \ No newline at end of file diff --git a/docs/0.11.8/data-model/operations/overview.html b/docs/0.11.8/data-model/operations/overview.html index ca505cab69..cc703ab36a 100644 --- a/docs/0.11.8/data-model/operations/overview.html +++ b/docs/0.11.8/data-model/operations/overview.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.11.8

    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, Queries are meant for reading data, and Actions are meant for changing it (either by updating existing entries or creating new ones).

    Keep reading to find out all there is to know about Operations in Wasp.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/data-model/operations/queries.html b/docs/0.11.8/data-model/operations/queries.html index bf2bebb161..0cd17c5f56 100644 --- a/docs/0.11.8/data-model/operations/queries.html +++ b/docs/0.11.8/data-model/operations/queries.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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.11.8/editor-setup.html b/docs/0.11.8/editor-setup.html index d504b5bf91..10935d29b2 100644 --- a/docs/0.11.8/editor-setup.html +++ b/docs/0.11.8/editor-setup.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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.11.8/general/cli.html b/docs/0.11.8/general/cli.html index f82a1b08c2..2a9b5fadfd 100644 --- a/docs/0.11.8/general/cli.html +++ b/docs/0.11.8/general/cli.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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

        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 and other cached artifacts.
                              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 current Wasp project.
        test                  Executes tests in your project.

    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)
       [2] saas
       [3] todo-ts
       ▸ 1

       🐝 --- Creating your project from the basic template... ---------------------------

       Created new Wasp app in ./MyFirstProject directory!
       To run it, do:

           cd MyFirstProject
           wasp 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 it, do:

           cd MyFirstProject
           wasp 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 .wasp/ directory...
      Deleted .wasp/ 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.

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

    • 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.11.8/general/language.html b/docs/0.11.8/general/language.html index a3c8a9214a..ddcb5fce15 100644 --- a/docs/0.11.8/general/language.html +++ b/docs/0.11.8/general/language.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.11.8

    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 Dashboard from "@client/Dashboard.js"
    }

    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)
        • ServerImport (external server import) (import Foo from "@server/bar.js", import { Smth } from "@server/a/b.js")
          • The path has to start with "@server". The rest is relative to the src/server directory.
          • import has to be a default import import Foo or a single named import import { Foo }.
        • ClientImport (external client import) (import Foo from "@client/bar.js", import { Smth } from "@client/a/b.js")
          • The path has to start with "@client". The rest is relative to the src/client 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.11.8/project/client-config.html b/docs/0.11.8/project/client-config.html index a2bc33878d..8e77c2381d 100644 --- a/docs/0.11.8/project/client-config.html +++ b/docs/0.11.8/project/client-config.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -35,7 +35,7 @@ renders a custom layout:

    src/client/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: ClientImport​

    You can use this function to perform any custom setup (e.g., setting up client-side periodic jobs).

    src/client/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.11.8/project/css-frameworks.html b/docs/0.11.8/project/css-frameworks.html index 7ef96bf8a0..a4203d25b8 100644 --- a/docs/0.11.8/project/css-frameworks.html +++ b/docs/0.11.8/project/css-frameworks.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    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
    ├── src
    │   ├── client
    │   │   ├── tsconfig.json
    │   │   ├── Main.css
    │   │   ├── MainPage.js
    │   │   └── waspLogo.png
    │   ├── server
    │   │   └── tsconfig.json
    │   └── shared
    │       └── tsconfig.json
    ├── 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
      /** @type {import('tailwindcss').Config} */
      module.exports = {
        content: [ "./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/client/Main.css
      @tailwind base;
      @tailwind components;
      @tailwind utilities;

      /* ... */

    4. Start using Tailwind 🥳

      ./src/client/MainPage.jsx
      // ...

      <h1 className="text-3xl font-bold underline">
        Hello world!
      </h1>

      // ...

    Adding Tailwind Plugins​

    To add Tailwind plugins, add it to dependencies in your main.wasp file and to the plugins list in your tailwind.config.cjs file:

    ./main.wasp
    app todoApp {
      // ...
      dependencies: [
        ("@tailwindcss/forms", "^0.5.3"),
        ("@tailwindcss/typography", "^0.5.7"),
      ],
      // ...
    }
    ./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.11.8/project/custom-vite-config.html b/docs/0.11.8/project/custom-vite-config.html index 52f6354422..5ca0521e3a 100644 --- a/docs/0.11.8/project/custom-vite-config.html +++ b/docs/0.11.8/project/custom-vite-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    Custom Vite Config

    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.

    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.

    src/client/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.

    src/client/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.

    src/client/vite.config.js
    export default {
      base: '/my-app/',
    }
    - - + + \ No newline at end of file diff --git a/docs/0.11.8/project/customizing-app.html b/docs/0.11.8/project/customizing-app.html index 974bda15cc..befff94500 100644 --- a/docs/0.11.8/project/customizing-app.html +++ b/docs/0.11.8/project/customizing-app.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.11.8

    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.11.1"
      },
      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.11.1"
      },
      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.11.1"
      },
      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.11.1"
      },
      title: "ToDo App",
      head: [
        "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto:300,400,500&display=swap\" />"
      ],
      auth: {
        // ...
      },
      client: {
        // ...
      },
      server: {
        // ...
      },
      db: {
        // ...
      },
      dependencies: [
        // ...
      ],
      emailSender: {
        // ...
      },
      webSocket: {
        // ...
      }
    }

    The app declaration has the following fields:

    • wasp: dict required Wasp compiler configuration. It is a dictionary with a single field:

      • version: string required

        The version specifies which versions of Wasp are compatible with the app. It should contain a valid SemVer range

        info

        For now, the version field only supports caret ranges (i.e., ^x.y.z). Support for the full specification will come in a future version of Wasp

    • title: string required

      Title of your app. It will appear in the browser tab, next to the favicon.

    • head: [string]

      List of additional lines (e.g. <link> or <script> tags) to be included in the <head> of your HTML document.

    The rest of the fields are covered in dedicated sections of the docs:

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/project/dependencies.html b/docs/0.11.8/project/dependencies.html index c3281c2406..3f9f82e432 100644 --- a/docs/0.11.8/project/dependencies.html +++ b/docs/0.11.8/project/dependencies.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.11.8

    Dependencies

    Specifying npm dependencies in Wasp project is done via the dependencies field in the app declaration, in the following way:

    app MyApp {
      title: "My app",
      // ...
      dependencies: [
        ("redux", "^4.0.5"),
        ("react-redux", "^7.1.3")
      ]
    }

    You will need to re-run wasp start after adding a dependency for Wasp to pick it up.

    The quickest way to find out the latest version of a package is to run:

    npm view <package-name> version
    Using Packages that are Already Used by Wasp Internally

    In the current implementation of Wasp, if Wasp is already internally using a certain npm dependency with a certain version specified, you are not allowed to define that same npm dependency yourself while specifying a different version. If you do that, you will get an error message telling you which exact version you have to use for that dependency. This means Wasp dictates exact versions of certain packages, so for example you can't choose version of React you want to use.

    We are currently working on a restructuring that will solve this and some other quirks that the current dependency system has: check issue #734 to follow our progress.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/project/env-vars.html b/docs/0.11.8/project/env-vars.html index 37f40c8b28..a5bc3bec0d 100644 --- a/docs/0.11.8/project/env-vars.html +++ b/docs/0.11.8/project/env-vars.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    Env Variables

    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.

    For instance, during development, you may want your project to connect to a local development database running on your machine, but 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.

    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.

    In Wasp, you can use environment variables in both the client and the server code.

    Client Env Vars​

    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 never store secrets in them (such as secret API keys).

    To enable Wasp to pick them up, client environment variables must be prefixed with REACT_APP_, for example: REACT_APP_SOME_VAR_NAME=....

    You can read them from the client code like this:

    src/App.js
    console.log(import.meta.env.REACT_APP_SOME_VAR_NAME)

    Check below on how to define them.

    Server Env Vars​

    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 SOME_VAR_NAME=....

    You can read them in the server code like this:

    console.log(process.env.SOME_VAR_NAME)

    Check below on how to define them.

    Defining Env Vars in Development​

    During development, there are two ways to provide env vars to your Wasp project:

    1. Using .env files. (recommended)
    2. Using shell. (useful for overrides)

    1. Using .env (dotenv) Files​

    Env vars usage in development

    This is the recommended method for providing env vars to your Wasp project during development.

    In the root of your Wasp project you can create two distinct files:

    • .env.server for env vars that will be provided to the server.

      Variables are defined in these files in the form of NAME=VALUE, for example:

      .env.server
      DATABASE_URL=postgresql://localhost:5432
      SOME_VAR_NAME=somevalue

    • .env.client for env vars that will be provided to the client.

      Variables are defined in these files in the form of NAME=VALUE, for example:

      .env.client
      REACT_APP_SOME_VAR_NAME=somevalue

    These files should not be committed to version control, and they are already ignored by default in the .gitignore file that comes with Wasp.

    2. Using Shell​

    If you set environment variables in the shell where you run your Wasp commands (e.g., wasp start), Wasp will recognize them.

    You can set environment variables in the .profile or a similar file, or by defining them at the start of a command:

    SOME_VAR_NAME=SOMEVALUE wasp start

    This is not specific to Wasp and is simply how environment variables can be set in the shell.

    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 overriding specific environment variables because environment variables set this way take precedence over those defined in .env files.

    Defining Env Vars in Production​

    While in development, we had the option of using .env files which made it easy to define and manage env vars. However, in production, we need to provide env vars differently.

    Env vars usage in development and production

    Client Env Vars​

    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 never store secrets in them (such as secret API keys).

    You should provide them to the build command, for example:

    REACT_APP_SOME_VAR_NAME=somevalue npm run build
    How it works

    What happens behind the scenes is that Wasp will replace all occurrences of 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.

    Read more about it in Vite's docs.

    Server Env Vars​

    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 Fly, you can define them using the flyctl CLI tool:

    flyctl secrets set SOME_VAR_NAME=somevalue

    You can read a lot more details in the deployment section of the docs. We go into detail on how to define env vars for each deployment option.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/project/server-config.html b/docs/0.11.8/project/server-config.html index c09c708799..22a195557a 100644 --- a/docs/0.11.8/project/server-config.html +++ b/docs/0.11.8/project/server-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    Server Config

    You can configure the behavior of the server via the server field of app declaration:

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      server: {
        setupFn: import { mySetupFunction } from "@server/myServerSetupCode.js",
        middlewareConfigFn: import { myMiddlewareConfigFn } from "@server/myServerSetupCode.js"
      }
    }

    Setup Function​

    Adding a Custom Route​

    As an example, adding a custom route would look something like:

    src/server/myServerSetupCode.ts
    export const mySetupFunction = async ({ app }) => {
      addCustomRoute(app)
    }

    function addCustomRoute(app) {
      app.get('/customRoute', (_req, res) => {
        res.send('I am a custom route')
      })
    }

    Storing Some Values for Later Use​

    In case you want to store some values for later use, or to be accessed by the Operations you do that in the setupFn function.

    Dummy example of such function and its usage:

    src/server/myServerSetupCode.js
    let someResource = undefined

    export const mySetupFunction = async () => {
      // Let's pretend functions setUpSomeResource and startSomeCronJob
      // are implemented below or imported from another file.
      someResource = await setUpSomeResource()
      startSomeCronJob()
    }

    export const getSomeResource = () => someResource
    src/server/queries.js
    import { getSomeResource } from './myServerSetupCode.js'

    ...

    export const someQuery = async (args, context) => {
      const someResource = getSomeResource()
      return queryDataFromSomeResource(args, someResource)
    }
    note

    The recommended way is to put the variable in the same module where you defined the setup function and then expose additional functions for reading those values, which you can then import directly from Operations and use.

    This effectively turns your module into a singleton whose construction is performed on server start.

    Read more about server setup function below.

    Middleware Config Function​

    You can configure the global middleware via the middlewareConfigFn. This will modify the middleware stack for all operations and APIs.

    Read more about middleware config function below.

    API Reference​

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      server: {
        setupFn: import { mySetupFunction } from "@server/myServerSetupCode.js",
        middlewareConfigFn: import { myMiddlewareConfigFn } from "@server/myServerSetupCode.js"
      }
    }

    app.server is a dictionary with the following fields:

    • setupFn: ServerImport​

      setupFn declares a function that will be executed on server start. This function is expected to be async and will be awaited before the server starts accepting any requests.

      It allows you to do any custom setup, e.g. setting up additional database/websockets or starting cron/scheduled jobs.

      The setupFn function receives the express.Application and the http.Server instances as part of its context. They can be useful for setting up any custom server routes or for example, setting up socket.io.

      src/server/myServerSetupCode.js
      export const mySetupFunction = async () => {
        await setUpSomeResource()
      }

    • middlewareConfigFn: ServerImport​

      The import statement to an Express middleware config function. This is a global modification affecting all operations and APIs. See more in the configuring middleware section.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/project/starter-templates.html b/docs/0.11.8/project/starter-templates.html index ec69eb7712..4ac6e80550 100644 --- a/docs/0.11.8/project/starter-templates.html +++ b/docs/0.11.8/project/starter-templates.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    Starter Templates

    We created a few starter templates to help you get started with Wasp. Check out the list below.

    Using a Template​

    Run wasp new to run the interactive mode for creating a new Wasp project.

    It will ask you for the project name, and then for the template to use:

    $ wasp new
    Enter the project name (e.g. my-project) ▸ MyFirstProject
    Choose a starter template
    [1] basic (default)
    [2] saas
    [3] todo-ts
    ▸ 1

    🐝 --- Creating your project from the basic template... ---------------------------

    Created new Wasp app in ./MyFirstProject directory!
    To run it, do:

        cd MyFirstProject
        wasp start

    Available Templates​

    When you have a good idea for a new product, you don't want to waste your time on setting up common things like authentication, database, etc. That's why we created a few starter templates to help you get started with Wasp.

    Vector Similarity Search Template​

    Vector Similarity Search Template

    A template for generating embeddings and performing vector similarity search on your text data!

    Features: w/ Embeddings & vector similarity search, OpenAI Embeddings API, Vector DB (Pinecone), Tailwind, Fullstack Type Safety

    Use this template:

    wasp new <project-name> -t embeddings

    SaaS Template​

    SaaS Template

    A SaaS Template to get your profitable side project started quickly and easily!

    Features: w/ Stripe Payments, OpenAI GPT API, Google Auth, SendGrid, Tailwind, & Cron Jobs

    Use this template:

    wasp new <project-name> -t saas

    Todo App w/ Typescript​

    A simple Todo App with Typescript and Fullstack Type Safety.

    Features: Auth (username/password), Fullstack Type Safety

    Use this template:

    wasp new <project-name> -t todo-ts
    - - + + \ No newline at end of file diff --git a/docs/0.11.8/project/static-assets.html b/docs/0.11.8/project/static-assets.html index 7da4f87bdd..391720d566 100644 --- a/docs/0.11.8/project/static-assets.html +++ b/docs/0.11.8/project/static-assets.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    Static Asset Handling

    Importing Asset as URL​

    Importing a static asset (e.g. an image) will return its URL. For example:

    src/client/App.jsx
    import imgUrl from './img.png'

    function App() {
      return <img src={imgUrl} alt="img" />
    }

    For example, imgUrl will be /img.png during development, and become /assets/img.2d8efhg.png in the production build.

    This is what you want to use most of the time, as it ensures that the asset file exists and is included in the bundle.

    We are using Vite under the hood, read more about importing static assets in Vite's docs.

    The public Directory​

    If you have assets that are:

    • Never referenced in source code (e.g. robots.txt)
    • Must retain the exact same file name (without hashing)
    • ...or you simply don't want to have to import an asset first just to get its URL

    Then you can place the asset in a special public directory in the client folder:

    src
    └── client
        ├── public
        │   ├── favicon.ico
        │   └── robots.txt
        └── ...

    Assets in this directory will be served at root path / during dev, and copied to the root of the dist directory as-is.

    For example, if you have a file favicon.ico in the public directory, and your app is hosted at https://myapp.com, it will be made available at https://myapp.com/favicon.ico.

    Usage in client code

    Note that:

    • You should always reference public assets using root absolute path - for example, src/client/public/icon.png should be referenced in source code as /icon.png.
    • Assets in the public directory cannot be imported from .
    - - + + \ No newline at end of file diff --git a/docs/0.11.8/project/testing.html b/docs/0.11.8/project/testing.html index 9686fcffcd..b83e39c68d 100644 --- a/docs/0.11.8/project/testing.html +++ b/docs/0.11.8/project/testing.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    Testing

    info

    Wasp is in beta, so keep in mind there might be some kinks / bugs, and possibly some changes with testing support in the future. If you encounter any issues, reach out to us on Discord and we will make sure to help you out!

    Testing Your React App​

    Wasp enables you to quickly and easily write both unit tests and React component tests for your frontend code. Because Wasp uses Vite, we support testing web apps through Vitest.

    Included Libraries

    vitest: Unit test framework with native Vite support.

    @vitest/ui: A nice UI for seeing your test results.

    jsdom: A web browser test environment for Node.js.

    @testing-library/react / @testing-library/jest-dom: Testing helpers.

    msw: A server mocking library.

    Writing Tests​

    For Wasp to pick up your tests, they should be placed within the src/client directory and use an extension that matches these glob patterns. Some of the file names that Wasp will pick up as tests:

    • yourFile.test.ts
    • YourComponent.spec.jsx

    Within test files, you can import your other source files as usual. For example, if you have a component Counter.jsx, you test it by creating a file in the same directory called Counter.test.jsx and import the component with import Counter from './Counter'.

    Running Tests​

    Running wasp test client will start Vitest in watch mode and recompile your Wasp project when changes are made.

    • If you want to see a realtime UI, pass --ui as an option.
    • To run the tests just once, use wasp test client run.

    All arguments after wasp test client are passed directly to the Vitest CLI, so check out their documentation for all of the options.

    Be Careful

    You should not run wasp test while wasp start is running. Both will try to compile your project to .wasp/out.

    React Testing Helpers​

    Wasp provides several functions to help you write React tests:

    • renderInContext: Takes a React component, wraps it inside a QueryClientProvider and Router, and renders it. This is the function you should use to render components in your React component tests.

      import { renderInContext } from "@wasp/test";

      renderInContext(<MainPage />);

    • mockServer: Sets up the mock server and returns an object containing the mockQuery and mockApi utilities. This should be called outside of any test case, in each file that wants to use those helpers.

      import { mockServer } from "@wasp/test";

      const { mockQuery, mockApi } = mockServer();

      • mockQuery: Takes a Wasp query to mock and the JSON data it should return.

        import getTasks from "@wasp/queries/getTasks";

        mockQuery(getTasks, []);
        • Helpful when your component uses useQuery.
        • Behind the scenes, Wasp uses msw to create a server request handle that responds with the specified data.
        • Mock are cleared between each test.

      • mockApi: Similar to mockQuery, but for APIs. Instead of a Wasp query, it takes a route containing an HTTP method and a path.

        import { HttpMethod } from "@wasp/types";

        mockApi({ method: HttpMethod.Get, path: "/foor/bar" }, { res: "hello" });

    Testing Your Server-Side Code​

    Wasp currently does not provide a way to test your server-side code, but we will be adding support soon. You can track the progress at this GitHub issue and express your interest by commenting.

    Examples​

    You can see some tests in a Wasp project here.

    Client Unit Tests​

    src/client/helpers.js
    export function areThereAnyTasks(tasks) {
      return tasks.length === 0;
    }
    src/client/helpers.test.js
    import { test, expect } from "vitest";

    import { areThereAnyTasks } from "./helpers";

    test("areThereAnyTasks", () => {
      expect(areThereAnyTasks([])).toBe(false);
    });

    React Component Tests​

    src/client/Todo.jsx
    import { useQuery } from "@wasp/queries";
    import getTasks from "@wasp/queries/getTasks";

    const Todo = (_props) => {
      const { data: tasks } = useQuery(getTasks);
      return (
        <ul>
          {tasks &&
            tasks.map((task) => (
              <li key={task.id}>
                <input type="checkbox" value={task.isDone} />
                {task.description}
              </li>
            ))}
        </ul>
      );
    };
    src/client/Todo.test.jsx
    import { test, expect } from "vitest";
    import { screen } from "@testing-library/react";

    import { mockServer, renderInContext } from "@wasp/test";
    import getTasks from "@wasp/queries/getTasks";
    import Todo from "./Todo";

    const { mockQuery } = mockServer();

    const mockTasks = [
      {
        id: 1,
        description: "test todo 1",
        isDone: true,
        userId: 1,
      },
    ];

    test("handles mock data", async () => {
      mockQuery(getTasks, mockTasks);

      renderInContext(<Todo />);

      await screen.findByText("test todo 1");

      expect(screen.getByRole("checkbox")).toBeChecked();

      screen.debug();
    });

    Testing With Mocked APIs​

    src/client/Todo.jsx
    import api from "@wasp/api";

    const Todo = (_props) => {
      const [tasks, setTasks] = useState([]);
      useEffect(() => {
        api
          .get("/tasks")
          .then((res) => res.json())
          .then((tasks) => setTasks(tasks))
          .catch((err) => window.alert(err));
      });

      return (
        <ul>
          {tasks &&
            tasks.map((task) => (
              <li key={task.id}>
                <input type="checkbox" value={task.isDone} />
                {task.description}
              </li>
            ))}
        </ul>
      );
    };
    src/client/Todo.test.jsx
    import { test, expect } from "vitest";
    import { screen } from "@testing-library/react";

    import { mockServer, renderInContext } from "@wasp/test";
    import Todo from "./Todo";

    const { mockApi } = mockServer();

    const mockTasks = [
      {
        id: 1,
        description: "test todo 1",
        isDone: true,
        userId: 1,
      },
    ];

    test("handles mock data", async () => {
      mockApi("/tasks", { res: mockTasks });

      renderInContext(<Todo />);

      await screen.findByText("test todo 1");

      expect(screen.getByRole("checkbox")).toBeChecked();

      screen.debug();
    });
    - - + + \ No newline at end of file diff --git a/docs/0.11.8/quick-start.html b/docs/0.11.8/quick-start.html index 747e2f7a76..9acd4397ba 100644 --- a/docs/0.11.8/quick-start.html +++ b/docs/0.11.8/quick-start.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.11.8

    Quick Start

    Installation​

    Try Wasp Without Installing 🤔?

    Give Wasp a spin in the browser without any setup by running our Wasp Template for Gitpod

    Welcome, new Waspeteer 🐝!

    To install Wasp on Linux / OSX / WSL(Win), open your terminal and run: 

    curl -sSL https://get.wasp-lang.dev/installer.sh | sh

    ℹ️ Wasp requires Node.js and will warn you if it is missing: check below for more details.

    Then, create a new app by running:

    wasp new

    and then run the app:

    cd <my-project-name>
    wasp start

    That's it 🎉 You have successfully created and served a new web app at http://localhost:3000 and Wasp is serving both frontend and backend for you.

    Something Unclear?

    Check More Details section below if anything went wrong, or if you have additional questions.

    What next?​

    • 👉 Check out the Todo App tutorial, which will take you through all the core features of Wasp! 👈
    • Setup your editor for working with Wasp.
    • Join us on Discord! Any feedback or questions you have, we are there for you.
    • Follow Wasp development by subscribing to our newsletter: https://wasp-lang.dev/#signup . We usually send 1 per month, and Matija does his best to unleash his creativity to make them engaging and fun to read :D!

    More details​

    Requirements​

    You must have Node.js (and NPM) installed on your machine and available in PATH. We rely on the latest Node.js LTS version (currently v18.14.2).

    We recommend using nvm for managing your Node.js installation version(s).

    Quick guide on installing/using nvm

    Install nvm via your OS package manager (apt, pacman, homebrew, ...) or via the nvm install script.

    Then, install a version of Node.js that you need:

    nvm install 18

    Finally, whenever you need to ensure a specific version of Node.js is used, run:

    nvm use 18

    to set the Node.js version for the current shell session.

    You can run

    node -v

    to check the version of Node.js currently being used in this shell session.

    Check NVM repo for more details: https://github.com/nvm-sh/nvm.

    Installation​

    Open your terminal and run:

    curl -sSL https://get.wasp-lang.dev/installer.sh | sh
    Running Wasp on Mac with Mx chip (arm64)

    Experiencing the 'Bad CPU type in executable' issue on a device with arm64 (Apple Silicon)? Given that the wasp binary is built for x86 and not for arm64 (Apple Silicon), you'll need to install Rosetta on your Mac if you are using a Mac with Mx (M1, M2, ...). Rosetta is a translation process that enables users to run applications designed for x86 on arm64 (Apple Silicon). To install Rosetta, run the following command in your terminal

    softwareupdate --install-rosetta

    Once Rosetta is installed, you should be able to run Wasp without any issues.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/telemetry.html b/docs/0.11.8/telemetry.html index ba054fda0c..346eb7d210 100644 --- a/docs/0.11.8/telemetry.html +++ b/docs/0.11.8/telemetry.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.11.8

    Telemetry

    Overview​

    The term telemetry refers to the collection of certain usage data to help improve the quality of a piece of software (in this case, Wasp).

    Our telemetry implementation is anonymized and very limited in its scope, focused on answering following questions:

    • How many people and how often: tried to install Wasp, use Wasp, have built a Wasp app, or have deployed one?
    • How many projects are created with Wasp?

    When and what is sent?​

    • Information is sent via HTTPS request when wasp CLI command is invoked. Information is sent no more than twice in a period of 12 hours (sending is paused for 12 hours after last invocation, separately for wasp build command and for all other commands). Exact information as it is sent:
      {
        // Randomly generated, non-identifiable UUID representing a user.
        "distinct_id": "bf3fa7a8-1c11-4f82-9542-ec1a2d28786b",
        // Non-identifiable hash representing a project.
        "project_hash": "6d7e561d62b955d1",
        // True if command was `wasp build`, false otherwise.
        "is_build": true,
        // Captures `wasp deploy ...` args, but only those from the limited, pre-defined list of keywords.
        // Those are "fly", "setup", "create-db", "deploy" and "cmd". Everything else is ommited.
        "deploy_cmd_args": "fly;deploy",
        "wasp_version": "0.1.9.1",
        "os": "linux",
        // "CI" if running on CI, and whatever is the content of "WASP_TELEMETRY_CONTEXT" env var.
        // We use this to track when execution is happening in some special context, like on Gitpod, Replit or similar.
        "context": "CI"
      }
    • Information is also sent once via HTTPS request when wasp is installed via install.sh script. Exact information as it is sent:
      {
        // Randomly generated id.
        "distinct_id": "274701613078193779564259",
        "os": "linux"
      }

    Opting out​

    You sharing the telemetry data with us means a lot to us, since it helps us understand how popular Wasp is, how it is being used, how the changes we are doing affect usage, how many new vs old users there are, and just in general how Wasp is doing. We look at these numbers every morning and they drive us to make Wasp better.

    However, if you wish to opt-out of telemetry, we understand! You can do so by setting the WASP_TELEMETRY_DISABLE environment variable to any value, e.g.:

    export WASP_TELEMETRY_DISABLE=1

    Future plans​

    We don't have this implemented yet, but the next step will be to make telemetry go in two directions -> instead of just sending usage data to us, it will also at the same time check for any messages from our side (e.g. notification about new version of Wasp, or a security notice). Link to corresponding github issue.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/tutorial/actions.html b/docs/0.11.8/tutorial/actions.html index 01c720be61..579f42391a 100644 --- a/docs/0.11.8/tutorial/actions.html +++ b/docs/0.11.8/tutorial/actions.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    6. Modifying Data

    In the previous section, we learned about using queries to fetch data and only briefly mentioned that actions can be used to update the database. Let's learn more about actions so we can add and update tasks in the database.

    We have to create:

    1. A Wasp action that creates a new task.
    2. A React form that calls that action when the user creates a task.

    Creating a New Action​

    Creating an action is very similar to creating a query.

    Declaring an Action​

    We must first declare the action in main.wasp:

    main.wasp
    // ...

    action createTask {
      fn: import { createTask } from "@server/actions.js",
      entities: [Task]
    }

    Implementing an Action​

    Let's now define a function for our createTask action:

    src/server/actions.js
    export const createTask = async (args, context) => {
      return context.entities.Task.create({
        data: { description: args.description },
      })
    }
    tip

    We put the function in a new file src/server/actions.ts, but we could have put it anywhere we wanted! There are no limitations here, as long as the declaration in the Wasp file imports it correctly and the file is located within src/server.

    Invoking the Action on the Client​

    First, let's define a form that the user can create new tasks with.

    src/client/MainPage.jsx
    import getTasks from '@wasp/queries/getTasks'
    import createTask from '@wasp/actions/createTask'
    import { useQuery } from '@wasp/queries'

    // ...

    const NewTaskForm = () => {
      const handleSubmit = async (event) => {
        event.preventDefault()
        try {
          const target = event.target
          const description = target.description.value
          target.reset()
          await createTask({ description })
        } catch (err) {
          window.alert('Error: ' + err.message)
        }
      }

      return (
        <form onSubmit={handleSubmit}>
          <input name="description" type="text" defaultValue="" />
          <input type="submit" value="Create task" />
        </form>
      )
    }

    Unlike queries, you call actions directly (i.e., without wrapping it with a hook) because we don't need reactivity. The rest is just regular React code.

    Now, we just need to add this form to the page component:

    src/client/MainPage.tsx
    import getTasks from '@wasp/queries/getTasks'
    import createTask from '@wasp/actions/createTask'
    import { useQuery } from '@wasp/queries'

    const MainPage = () => {
      const { data: tasks, isLoading, error } = useQuery(getTasks)

      return (
        <div>
          <NewTaskForm />

          {tasks && <TasksList tasks={tasks} />}

          {isLoading && 'Loading...'}
          {error && 'Error: ' + error}
        </div>
      )
    }

    And now we have a form that creates new tasks.

    Try creating a "Build a Todo App in Wasp" task and see it appear in the list below. The task is created on the server and saved in the database.

    Try refreshing the page or opening it in another browser, you'll see the tasks are still there!

    Todo App - creating new task

    Automatic Query Invalidation

    When you create a new task, the list of tasks is automatically updated to display the new task, even though we have not written any code that would do that! These automatic updates are handled by code that Wasp generates.

    When you declared the getTasks and createTask operations, you specified that they both use the Task entity. So when createTask is called, Wasp knows that the data getTasks fetches may have changed and automatically updates it in the background. This means that out of the box, Wasp will make sure that all your queries are kept in-sync with changes made by any actions.

    This behavior is convenient as a default but can cause poor performance in large apps. While there is no mechanism for overriding this behavior yet, it is something that we plan to include in Wasp in the future. This feature is tracked here.

    A Second Action​

    Our Todo app isn't finished if you can't mark a task as done! We'll create a new action to update a task's status and call it from React whenever a task's checkbox is toggled.

    Since we've already created one task together, try to create this one yourself. It should be an action named updateTask that takes a task id and an isDone in its arguments. You can check our implementation below.

    Solution

    The action declaration:

    main.wasp
    // ...

    action updateTask {
      fn: import { updateTask } from "@server/actions.js",
      entities: [Task]
    }

    The implementation on the server:

    src/server/actions.js
    // ...

    export const updateTask = async ({ id, isDone }, context) => {
      return context.entities.Task.update({
        where: { id },
        data: {
          isDone: isDone,
        },
      })
    }

    Now, we can call updateTask from the React component:

    src/client/MainPage.jsx
    // ...
    import updateTask from '@wasp/actions/updateTask'

    // ...

    const Task = ({ task }) => {
      const handleIsDoneChange = async (event) => {
        try {
          await updateTask({
            id: task.id,
            isDone: event.target.checked,
          })
        } catch (error) {
          window.alert('Error while updating task: ' + error.message)
        }
      }

      return (
        <div>
          <input
            type="checkbox"
            id={String(task.id)}
            checked={task.isDone}
            onChange={handleIsDoneChange}
          />
          {task.description}
        </div>
      )
    }
    // ...

    Awesome! Now we can check off this task 🙃 Let's add one more interesting feature to our app.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/tutorial/auth.html b/docs/0.11.8/tutorial/auth.html index 5aa30de9a5..516727c688 100644 --- a/docs/0.11.8/tutorial/auth.html +++ b/docs/0.11.8/tutorial/auth.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    7. Adding Authentication

    Most apps today require some sort of registration and login flow, so Wasp has first-class support for it. Let's add it to our Todo app!

    First, we'll create a Todo list for what needs to be done (luckily we have an app for this now 😄).

    • Create a User entity.
    • Tell Wasp to use the username and password authentication.
    • Add login and signup pages.
    • Update the main page to require authentication.
    • Add a relation between User and Task entities.
    • Modify our queries and actions so that users can only see and modify their tasks.
    • Add a logout button.

    Creating a User Entity​

    Since Wasp manages authentication, it expects certain fields to exist on the User entity. Specifically, it expects a unique username field and a password field, both of which should be strings.

    main.wasp
    // ...

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

    As we talked about earlier, we have to remember to update the database schema:

    wasp db migrate-dev

    Adding Auth to the Project​

    Next, we want to tell Wasp that we want to use full-stack authentication in our app:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.11.0"
      },
      title: "Todo app",

      auth: {
        // Tells Wasp which entity to use for storing users.
        userEntity: User,
        methods: {
          // Enable username and password auth.
          usernameAndPassword: {}
        },
        // We'll see how this is used a bit later.
        onAuthFailedRedirectTo: "/login"
      }
    }

    // ...

    By doing this, Wasp will create:

    • Auth UI with login and signup forms.
    • A logout() action.
    • A React hook useAuth().
    • context.user for use in Queries and Actions.
    info

    Wasp also supports authentication using Google, GitHub, and email, with more on the way!

    Adding Login and Signup Pages​

    Wasp creates the login and signup forms for us, but we still need to define the pages to display those forms on. We'll start by declaring the pages in the Wasp file:

    main.wasp
    // ...

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import Signup from "@client/SignupPage.jsx"
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import Login from "@client/LoginPage.jsx"
    }

    Great, Wasp now knows these pages exist! Now, the React code for the pages:

    src/client/LoginPage.jsx
    import { Link } from 'react-router-dom'
    import { LoginForm } from '@wasp/auth/forms/Login'

    const LoginPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <LoginForm />
          <br />
          <span>
            I don't have an account yet (<Link to="/signup">go to signup</Link>).
          </span>
        </div>
      )
    }

    export default LoginPage

    The Signup page is very similar to the login one:

    src/client/SignupPage.jsx
    import { Link } from 'react-router-dom'
    import { SignupForm } from '@wasp/auth/forms/Signup'

    const SignupPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <SignupForm />
          <br />
          <span>
            I already have an account (<Link to="/login">go to login</Link>).
          </span>
        </div>
      )
    }

    export default SignupPage

    Update the Main Page to Require Auth​

    We don't want users who are not logged in to access the main page, because they won't be able to create any tasks. So let's make the page private by requiring the user to be logged in:

    main.wasp
    // ...

    page MainPage {
      authRequired: true,
      component: import Main from "@client/MainPage"
    }

    Now that auth is required for this page, unauthenticated users will be redirected to /login, as we specified with app.auth.onAuthFailedRedirectTo.

    Additionally, when authRequired is true, the page's React component will be provided a user object as prop.

    src/client/MainPage.jsx
    const MainPage = ({ user }) => {
      // Do something with the user
    }

    Ok, time to test this out. Navigate to the main page (/) of the app. You'll get redirected to /login, where you'll be asked to authenticate.

    Since we just added users, you don't have an account yet. Go to the signup page and create one. You'll be sent back to the main page where you will now be able to see the TODO list!

    Let's check out what the database looks like. Start the Prisma Studio:

    wasp db studio
    Database demonstration - password hashing

    We see there is a user and that its password is already hashed 🤯

    However, you will notice that if you try logging in as different users and creating some tasks, all users share the same tasks. That's because we haven't yet updated the queries and actions to have per-user tasks. Let's do that next.

    Defining a User-Task Relation​

    First, let's define a one-to-many relation between users and tasks (check the Prisma docs on relations):

    main.wasp
    // ...

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

    entity Task {=psl
        id          Int     @id @default(autoincrement())
        description String
        isDone      Boolean @default(false)
        user        User?    @relation(fields: [userId], references: [id])
        userId      Int?
    psl=}

    // ...

    As always, we have to update the database:

    wasp db migrate-dev
    note

    We made user and userId in Task optional (via ?) because that allows us to keep the existing tasks, which don't have a user assigned, in the database. This is not recommended because it allows an unwanted state in the database (what is the purpose of the task not belonging to anybody?) and normally we would not make these fields optional. Instead, we would do a data migration to take care of those tasks, even if it means just deleting them all. However, for this tutorial, for the sake of simplicity, we will stick with this.

    Updating Operations to Check Authentication​

    Next, let's update the queries and actions to forbid access to non-authenticated users and to operate only on the currently logged-in user's tasks:

    src/server/queries.js
    import HttpError from '@wasp/core/HttpError.js'

    export const getTasks = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.findMany({
        where: { user: { id: context.user.id } },
        orderBy: { id: 'asc' },
      })
    }
    src/server/actions.js
    import HttpError from '@wasp/core/HttpError.js'

    export const createTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.create({
        data: {
          description: args.description,
          user: { connect: { id: context.user.id } },
        },
      })
    }

    export const updateTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.updateMany({
        where: { id: args.id, user: { id: context.user.id } },
        data: { isDone: args.isDone },
      })
    }
    note

    Due to how Prisma works, we had to convert update to updateMany in updateTask action to be able to specify the user id in where.

    With these changes, each user should have a list of tasks that only they can see and edit.

    Try playing around, adding a few users and some tasks for each of them. Then open the DB studio:

    wasp db studio
    Database demonstration

    You will see that each user has their tasks, just as we specified in our code!

    Logout Button​

    Last, but not least, let's add the logout functionality:

    src/client/MainPage.jsx
    // ...
    import logout from '@wasp/auth/logout'
    //...

    const MainPage = () => {
      // ...
      return (
        <div>
          // ...
          <button onClick={logout}>Logout</button>
        </div>
      )
    }

    This is it, we have a working authentication system, and our Todo app is multi-user!

    What's Next?​

    We did it 🎉 You've followed along with this tutorial to create a basic Todo app with Wasp.

    You should be ready to learn about more complicated features and go more in-depth with the features already covered. Scroll through the sidebar on the left side of the page to see every feature Wasp has to offer. Or, let your imagination run wild and start building your app! ✨

    Looking for inspiration?

    note

    If you notice that some of the features you'd like to have are missing, or have any other kind of feedback, please write to us on Discord or create an issue on Github, so we can learn which features to add/improve next 🙏

    If you would like to contribute or help to build a feature, let us know! You can find more details on contributing here.

    Oh, and do subscribe to our newsletter! We usually send one per month, and Matija does his best to unleash his creativity to make them engaging and fun to read :D!

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/tutorial/create.html b/docs/0.11.8/tutorial/create.html index 6486cbce06..ba6f4866a2 100644 --- a/docs/0.11.8/tutorial/create.html +++ b/docs/0.11.8/tutorial/create.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    1. Creating a New Project

    info

    You'll need to have the latest version of Wasp installed locally to follow this tutorial. If you haven't installed it yet, check out the QuickStart guide!

    In this section, we'll guide you through the process of creating a simple Todo app with Wasp. In the process, we'll take you through the most important and useful features of Wasp.

    How Todo App will work once it is done

    If you get stuck at any point (or just want to chat), reach out to us on Discord and we will help you!

    You can find the complete code of the app we're about to build here.

    See Wasp In Action

    Prefer videos? We have a YouTube tutorial whick walks you through building this Todo app step by step. Check it out here!.

    We've also set up an in-browser dev environment for you on Gitpod which allows you to view and edit the completed app with no installation required.

    Creating a Project​

    To setup a new Wasp project, run the following command in your terminal

    $ wasp new TodoApp

    Enter the newly created directory and start the development server:

    $ cd TodoApp
    $ wasp start
    note

    wasp start will take a bit of time to start the server the first time you run it in a new project.

    You will see log messages from the client, server, and database setting themselves up. When everything is ready, a new tab should open in your browser at http://localhost:3000 with a simple placeholder plage:

    Screenshot of new Wasp app

    Wasp has generated for you the full front-end and back-end code the app! Next, we'll take a closer look at how the project is structured.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/tutorial/entities.html b/docs/0.11.8/tutorial/entities.html index 179dfa1291..075c740992 100644 --- a/docs/0.11.8/tutorial/entities.html +++ b/docs/0.11.8/tutorial/entities.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    4. Database Entities

    Entities are one of the most important concepts in Wasp and are how you define what gets stored in the database.

    Since our Todo app is all about tasks, we will define a Task entity in the Wasp file:

    main.wasp
    // ...

    entity Task {=psl
        id          Int     @id @default(autoincrement())
        description String
        isDone      Boolean @default(false)
    psl=}
    note

    Wasp uses Prisma as a way to talk to the database. You define entities by defining Prisma models using the Prisma Schema Language (PSL) between the {=psl psl=} tags.

    Read more in the Entities section of the docs.

    To update the database schema to include this entity, stop the wasp start process, if its running, and run:

    wasp db migrate-dev

    You'll need to do this any time you change an entity's definition. It instructs Prisma to create a new database migration and apply it to the database.

    To take a look at the database and the new Task entity, run:

    wasp db studio

    This will open a new page in your browser to view and edit the data in your database.

    Todo App - Db studio showing Task schema

    Click on the Task entity and check out its fields! We don't have any data in our database yet, but we are about to change that.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/tutorial/pages.html b/docs/0.11.8/tutorial/pages.html index 17beccf986..f45d927d85 100644 --- a/docs/0.11.8/tutorial/pages.html +++ b/docs/0.11.8/tutorial/pages.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    3. Pages & Routes

    In the default main.wasp file created by wasp new, there is a page and a route declaration:

    main.wasp
    route RootRoute { path: "/", to: MainPage }

    page MainPage {
      // We specify that the React implementation of the page is the default export
      // of `src/client/MainPage.jsx`. This statement uses standard JS import syntax.
      // Use `@client` to reference files inside the `src/client` folder.
      component: import Main from "@client/MainPage.jsx"
    }

    Together, these declarations tell Wasp that when a user navigates to /, it should render the default export from src/client/MainPage.

    The MainPage Component​

    Let's take a look at the React component referenced by the page declaration:

    src/client/MainPage.jsx
    import waspLogo from './waspLogo.png'
    import './Main.css'

    const MainPage = () => {
      // ...
    }
    export default MainPage

    Since Wasp uses React for the frontend, this is a normal functional React component. It also uses the CSS and logo image that are located next to it in the src/client folder.

    That is all the code you need! Wasp takes care of everything else necessary to define, build, and run the web app.

    tip

    wasp start automatically picks up the changes you make and restarts the app, so keep it running in the background.

    Adding a Second Page​

    To add more pages, you can create another set of page and route declarations. You can even add parameters to the URL path, using the same syntax as React Router. Let's test this out by adding a new page:

    main.wasp
    route HelloRoute { path: "/hello/:name", to: HelloPage }
    page HelloPage {
      component: import Hello from "@client/HelloPage.jsx"
    }

    When a user visits /hello/their-name, Wasp will render the component exported from src/client/HelloPage and pass the URL parameter the same way as in React Router:

    src/client/HelloPage.jsx
    const HelloPage = (props) => {
      return <div>Here's {props.match.params.name}!</div>
    }

    export default HelloPage

    Now you can visit /hello/johnny and see "Here's johnny!"

    Cleaning Up​

    Let's prepare for building the Todo app by cleaning up the project and removing files and code we won't need. Start by deleting Main.css, waspLogo.png, and HelloPage.tsx that we just created in the src/client/ folder.

    Since we deleted HelloPage.tsx, we also need to remember to remove the route and page declarations we wrote for it. Your Wasp file should now look like this:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.11.0"
      },
      title: "Todo app"
    }

    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      component: import Main from "@client/MainPage.jsx"
    }

    Next, we'll remove most of the code from the MainPage component:

    src/client/MainPage.jsx
    const MainPage = () => {
      return <div>Hello world!</div>
    }

    export default MainPage

    At this point, the main page should look like this:

    Todo App - Hello World

    In the next section, we'll start implementing some features of the Todo app!

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/tutorial/project-structure.html b/docs/0.11.8/tutorial/project-structure.html index 211d0191a0..5b74f0f7b8 100644 --- a/docs/0.11.8/tutorial/project-structure.html +++ b/docs/0.11.8/tutorial/project-structure.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.11.8

    2. Project Structure

    After creating a new Wasp project, you'll get a file structure that looks like this:

    .
    ├── .gitignore
    ├── main.wasp              # Your Wasp code goes here.
    ├── src
    │   ├── client             # Your client code (JS/CSS/HTML) goes here.
    │   │   ├── Main.css
    │   │   ├── MainPage.jsx
    │   │   ├── tsconfig.json
    │   │   ├── vite.config.ts
    │   │   ├── vite-env.d.ts
    │   │   └── waspLogo.png
    │   ├── server             # Your server code (Node JS) goes here.
    │   │   └── tsconfig.json
    │   ├── shared             # Your shared (runtime independent) code goes here.
    │   │   └── tsconfig.json
    │   └── .waspignore
    └── .wasproot

    By your code, we mean the "the code you write", as opposed to the code generated by Wasp. Wasp expects you to separate all of your code—which we call external code—into three folders to make it obvious how each file is executed:

    • src/client: Contains the code executed on the client, in the browser.
    • src/server: Contains the code executed on the server, with Node.
    • src/shared: Contains code that may be executed on both the client and server.

    Many of the other files (tsconfig.json, vite-env.d.ts, etc.) are used by your IDE to improve your development experience with tools like autocompletion, intellisense, and error reporting. The file vite.config.ts is used to configure Vite, Wasp's build tool of choice. We won't be configuring Vite in this tutorial, so you can safely ignore the file. Still, if you ever end up wanting more control over Vite, you'll find everything you need to know in custom Vite config docs.

    TypeScript Support

    Wasp supports TypeScript out of the box, but you are free to choose between or mix JavaScript and TypeScript as you see fit.

    We'll provide you with both JavaScript and TypeScript code in this tutorial. Code blocks will have a toggle to switch between vanilla 🍦 JavaScript and TypeScript.

    The most important file in the project is main.wasp. Wasp uses the configuration within it to perform its magic. Based on what you write, it generates a bunch of code for your database, server-client communication, React routing, and more.

    Let's look a bit closer at main.wasp.

    main.wasp​

    This file, written in our Wasp configuration language, defines your app and lets Wasp take care a ton of features to your app for you. The file contains several declarations which, together, describe all the components of your app.

    The default Wasp file generated via wasp new on the previous page looks like:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.11.6" // Pins the version of Wasp to use.
      },
      title: "Todo app" // Used as the browser tab title. Note that all strings in Wasp are double quoted!
    }

    route RootRoute { path: "/", to: MainPage }

    page MainPage {
      // We specify that the React implementation of the page is the default export
      // of `src/client/MainPage.jsx`. This statement uses standard JS import syntax.
      // Use `@client` to reference files inside the `src/client` folder.
      component: import Main from "@client/MainPage.jsx"
    }

    This file uses three declaration types:

    • app: Top-level configuration information about your app.

    • route: Describes which path each page should be accessible from.

    • page: Defines a web page and the React component that will be rendered when the page is loaded.

    In the next section, we'll explore how route and page work together to build your web app.

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/tutorial/queries.html b/docs/0.11.8/tutorial/queries.html index 8e5c39eb2d..c37749bcb4 100644 --- a/docs/0.11.8/tutorial/queries.html +++ b/docs/0.11.8/tutorial/queries.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.11.8

    5. Querying the Database

    We want to know which tasks we need to do, so let's list them! The primary way of interacting with entities in Wasp is by using queries and actions, collectively known as operations.

    Queries are used to read an entity, while actions are used to create, modify, and delete entities. Since we want to list the tasks, we'll want to use a query.

    To list tasks we have to:

    1. Create a query that fetches tasks from the database.
    2. Update the MainPage.tsx to use that query and display the results.

    Defining the Query​

    We'll create a new query called getTasks. We'll need to declare the query in the Wasp file and write its implementation in .

    Declaring a Query​

    We need to add a query declaration to main.wasp so that Wasp knows it exists:

    main.wasp
    // ...

    query getTasks {
      // Specifies where the implementation for the query function is.
      // Use `@server` to import files inside the `src/server` folder.
      fn: import { getTasks } from "@server/queries.js",
      // Tell Wasp that this query reads from the `Task` entity. By doing this, Wasp
      // will automatically update the results of this query when tasks are modified.
      entities: [Task]
    }

    Implementing a Query​

    src/server/queries.js
    export const getTasks = async (args, context) => {
      return context.entities.Task.findMany({
        orderBy: { id: 'asc' },
      })
    }

    Query function parameters:

    • args: object, arguments the query is given by the caller.
    • context: object, information provided by Wasp.

    Since we declared in main.wasp that our query uses the Task entity, Wasp injected a Prisma client for the Task entity as context.entities.Task - we used it above to fetch all the tasks from the database.

    info

    Queries and actions are NodeJS functions that are executed on the server. Therefore, we put them in the src/server folder.

    Invoking the Query On the Frontend​

    While we implement queries on the server, Wasp generates client-side functions that automatically takes care of serialization, network calls, and chache invalidation, allowing you to call the server code like it's a regular function. This makes it easy for us to use the getTasks query we just created in our React component:

    src/client/MainPage.jsx
    import getTasks from '@wasp/queries/getTasks'
    import { useQuery } from '@wasp/queries'

    const MainPage = () => {
      const { data: tasks, isLoading, error } = useQuery(getTasks)

      return (
        <div>
          {tasks && <TasksList tasks={tasks} />}

          {isLoading && 'Loading...'}
          {error && 'Error: ' + error}
        </div>
      )
    }

    const Task = ({ task }) => {
      return (
        <div>
          <input type="checkbox" id={String(task.id)} checked={task.isDone} />
          {task.description}
        </div>
      )
    }

    const TasksList = ({ tasks }) => {
      if (!tasks?.length) return <div>No tasks</div>

      return (
        <div>
          {tasks.map((task, idx) => (
            <Task task={task} key={idx} />
          ))}
        </div>
      )
    }

    export default MainPage

    Most of this code is regular React, the only exception being the special @wasp imports:

    We could have called the query directly using getTasks(), but the useQuery hook makes it reactive: React will re-render the component every time the query changes. Remember that Wasp automatically refreshes queries whenever the data is modified.

    With these changes, you should be seeing the text "No tasks" on the screen:

    Todo App - No Tasks

    We'll create a form to add tasks in the next step 🪄

    - - + + \ No newline at end of file diff --git a/docs/0.11.8/vision.html b/docs/0.11.8/vision.html index 65ce7ff264..31d2399bbe 100644 --- a/docs/0.11.8/vision.html +++ b/docs/0.11.8/vision.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -33,7 +33,7 @@ They can be used inline (mixed with Wasp code) or provided via external files.
  • Has hatches (escape mechanisms) that allow you to customize your web app in all the right places, but remain hidden until you need them.
  • Entity (data model) is a first-class citizen - defined via custom Wasp syntax and it integrates very closely with the rest of the features, serving as one of the central concepts around which everything is built.
  • Out of the box support for CRUD UI based on the Entities, to get you quickly going, but also customizable to some level.
  • "Smart" operations (queries and actions) that in most cases automatically figure out when to update, and if not it is easy to define custom logic to compensate for that. User worries about client-server gap as little as possible.
  • Support, directly in Wasp, for declaratively defining simple components and operations.
  • Besides Wasp as a programming language, there will also be a visual builder that generates/edits Wasp code, allowing non-developers to participate in development. Since Wasp is declarative, we imagine such builder to naturally follow from Wasp language.
  • Server side rendering, caching, packaging, security, ... -> all those are taken care of by Wasp. You tell Wasp what you want, and Wasp figures out how to do it.
  • As simple deployment to production/staging as it gets.
  • While it comes with the official implementation(s), Wasp language will not be coupled with the single implementation. Others can provide implementations that compile to different web app stacks.
    • - - + + \ No newline at end of file diff --git a/docs/0.11.8/writingguide.html b/docs/0.11.8/writingguide.html index 6c7cc0e410..9d6b2e81c0 100644 --- a/docs/0.11.8/writingguide.html +++ b/docs/0.11.8/writingguide.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -53,7 +53,7 @@ Many of our titles are currently in title-case, we should start phasing those out.
  • Use the Oxford comma (e.g., "a, b, and c" instead of "a, b and c"). Why the Oxford comma is important

    • 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/0.12.0.html b/docs/0.12.0.html index 9dbd2fcc8d..dbae078ed5 100644 --- a/docs/0.12.0.html +++ b/docs/0.12.0.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -30,7 +30,7 @@ which are in their essence a Node.js functions that execute on server and can, thanks to Wasp, very easily be called from the client.

    First, we define these Operations in our main.wasp file, so Wasp knows about them and can "beef them up":

    main.wasp
    // Queries have automatic cache invalidation and are type-safe.
    query getRecipes {
      fn: import { getRecipes } from "@src/recipe/operations.ts",
      entities: [Recipe],
    }

    // Actions are type-safe and can be used to perform side-effects.
    action addRecipe {
      fn: import { addRecipe } from "@src/recipe/operations.ts",
      entities: [Recipe],
    }

    ... and then implement them in our Javascript (or TypeScript) code (we show just the query here, using TypeScript):

    src/recipe/operations.ts
    // Wasp generates the types for you.
    import { type GetRecipes } from "wasp/server/operations";
    import { type Recipe } from "wasp/entities";

    export const getRecipes: GetRecipes<{}, Recipe[]> = async (_args, context) => {
      return context.entities.Recipe.findMany( // Prisma query
        { where: { user: { id: context.user.id } } }
      );
    };

    export const addRecipe ...

    Now we can very easily use these in our React components!

    For the end, let's create a home page of our app.

    First we define it in main.wasp:

    main.wasp
    ...

    route HomeRoute { path: "/", to: HomePage }
    page HomePage {
      component: import { HomePage } from "@src/pages/HomePage",
      authRequired: true // Will send user to /login if not authenticated.
    }

    and then implement it as a React component in JS/TS (that calls the Operations we previously defined):

    src/pages/HomePage.tsx
    import { useQuery, getRecipes } from "wasp/client/operations";
    import { type User } from "wasp/entities";

    export function HomePage({ user }: { user: User }) {
      // Due to full-stack type safety, `recipes` will be of type `Recipe[]` here.
      const { data: recipes, isLoading } = useQuery(getRecipes); // Calling our query here!

      if (isLoading) {
        return <div>Loading...</div>;
      }

      return (
        <div>
          <h1>Recipes</h1>
          <ul>
            {recipes ? recipes.map((recipe) => (
              <li key={recipe.id}>
                <div>{recipe.title}</div>
                <div>{recipe.description}</div>
              </li>
            )) : 'No recipes defined yet!'}
          </ul>
        </div>
      );
    }

    And voila! We are listing all the recipes in our app 🎉

    This was just a quick example to give you a taste of what Wasp is. For step by step tour through the most important Wasp features, check out the Todo app tutorial.

    note

    Above we skipped defining /login and /signup pages to keep the example a bit shorter, but those are very simple to do by using Wasp's Auth UI feature.

    When to use Wasp​

    Wasp is addressing the same core problems that typical web app frameworks are addressing, and it in big part looks, swims and quacks like a web app framework.

    Best used for​

    • building full-stack web apps (like e.g. Airbnb or Asana)
    • quickly starting a web app with industry best practices
    • to be used alongside modern web dev stack (currently supported React and Node)

    Avoid using Wasp for​

    • building static/presentational websites
    • to be used as a no-code solution
    • to be a solve-it-all tool in a single language

    Wasp is a DSL​

    note

    You don't need to know what a DSL is to use Wasp, but if you are curious, you can read more about it below.

    Wasp does not match typical expectations of a web app framework: it is not a set of libraries, it is instead a simple programming language that understands your code and can do a lot of things for you.

    Wasp is a programming language, but a specific kind: it is specialized for a single purpose: building modern web applications. We call such languages DSLs (Domain Specific Language).

    Other examples of DSLs that are often used today are e.g. SQL for databases and HTML for web page layouts. The main advantage and reason why DSLs exist is that they need to do only one task (e.g. database queries) so they can do it well and provide the best possible experience for the developer.

    The same idea stands behind Wasp - a language that will allow developers to build modern web applications with 10x less code and less stack-specific knowledge.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/advanced/apis.html b/docs/0.12.0/advanced/apis.html index 38b394d0b9..2af9e6077a 100644 --- a/docs/0.12.0/advanced/apis.html +++ b/docs/0.12.0/advanced/apis.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.12.0

    Custom HTTP API Endpoints

    In Wasp, the default client-server interaction mechanism is through Operations. However, if you need a specific URL method/path, or a specific response, Operations may not be suitable for you. For these cases, you can use an api. Best of all, they should look and feel very familiar.

    How to Create an API​

    APIs are used to tie a JS function to a certain endpoint e.g. POST /something/special. They are distinct from Operations and have no client-side helpers (like useQuery).

    To create a Wasp API, you must:

    1. Declare the API in Wasp using the api declaration
    2. Define the API's NodeJS implementation

    After completing these two steps, you'll be able to call the API from the client code (via our Axios wrapper), or from the outside world.

    Declaring the API in Wasp​

    First, we need to declare the API in the Wasp file and you can easily do this with the api declaration:

    main.wasp
    // ...

    api fooBar { // APIs and their implementations don't need to (but can) have the same name.
      fn: import { fooBar } from "@src/apis",
      httpRoute: (GET, "/foo/bar")
    }

    Read more about the supported fields in the API Reference.

    Defining the API's NodeJS Implementation​

    After you defined the API, it should be implemented as a NodeJS function that takes three arguments:

    1. req: Express Request object
    2. res: Express Response object
    3. context: An additional context object injected into the API by Wasp. This object contains user session information, as well as information about entities. The examples here won't use the context for simplicity purposes. You can read more about it in the section about using entities in APIs.
    src/apis.js
    export const fooBar = (req, res, context) => {
      res.set("Access-Control-Allow-Origin", "*"); // Example of modifying headers to override Wasp default CORS middleware.
      res.json({ msg: `Hello, ${context.user ? "registered user" : "stranger"}!` });
    };

    Using the API​

    Using the API externally​

    To use the API externally, you simply call the endpoint using the method and path you used.

    For example, if your app is running at https://example.com then from the above you could issue a GET to https://example/com/foo/callback (in your browser, Postman, curl, another web service, etc.).

    Using the API from the Client​

    To use the API from your client, including with auth support, you can import the Axios wrapper from wasp/client/api and invoke a call. For example:

    src/pages/SomePage.jsx
    import React, { useEffect } from "react";
    import { api } from "wasp/client/api";

    async function fetchCustomRoute() {
      const res = await api.get("/foo/bar");
      console.log(res.data);
    }

    export const Foo = () => {
      useEffect(() => {
        fetchCustomRoute();
      }, []);

      return <>// ...</>;
    };

    Making Sure CORS Works​

    APIs are designed to be as flexible as possible, hence they don't utilize the default middleware like Operations do. As a result, to use these APIs on the client side, you must ensure that CORS (Cross-Origin Resource Sharing) is enabled.

    You can do this by defining custom middleware for your APIs in the Wasp file.

    For example, an apiNamespace is a simple declaration used to apply some middlewareConfigFn to all APIs under some specific path:

    main.wasp
    apiNamespace fooBar {
      middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@src/apis",
      path: "/foo"
    }

    And then in the implementation file:

    src/apis.js
    export const apiMiddleware = (config) => {
      return config;
    };

    We are returning the default middleware which enables CORS for all APIs under the /foo path.

    For more information about middleware configuration, please see: Middleware Configuration

    Using Entities in APIs​

    In many cases, resources used in APIs will be Entities. To use an Entity in your API, add it to the api declaration in Wasp:

    main.wasp
    api fooBar {
      fn: import { fooBar } from "@src/apis",
      entities: [Task],
      httpRoute: (GET, "/foo/bar")
    }

    Wasp will inject the specified Entity into the APIs context argument, giving you access to the Entity's Prisma API:

    src/apis.js
    export const fooBar = (req, res, context) => {
      res.json({ count: await context.entities.Task.count() });
    };

    The object context.entities.Task exposes prisma.task from Prisma's CRUD API.

    API Reference​

    main.wasp
    api fooBar {
      fn: import { fooBar } from "@src/apis",
      httpRoute: (GET, "/foo/bar"),
      entities: [Task],
      auth: true,
      middlewareConfigFn: import { apiMiddleware } from "@src/apis"
    }

    The api declaration has the following fields:

    • fn: ExtImport required

      The import statement of the APIs NodeJs implementation.

    • httpRoute: (HttpMethod, string) required

      The HTTP (method, path) pair, where the method can be one of:

      • ALL, GET, POST, PUT or DELETE
      • and path is an Express path string.

    • entities: [Entity]

      A list of entities you wish to use inside your API. You can read more about it here.

    • auth: bool

      If auth is enabled, this will default to true and provide a context.user object. If you do not wish to attempt to parse the JWT in the Authorization Header, you should set this to false.

    • middlewareConfigFn: ExtImport

      The import statement to an Express middleware config function for this API. See more in middleware section of the docs.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/advanced/deployment/cli.html b/docs/0.12.0/advanced/deployment/cli.html index 40222c20b0..dcd1439e5e 100644 --- a/docs/0.12.0/advanced/deployment/cli.html +++ b/docs/0.12.0/advanced/deployment/cli.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.12.0

    Deploying with the Wasp CLI

    Wasp CLI can deploy your full-stack application with only a single command. The command automates the manual deployment process and is the recommended way of deploying Wasp apps.

    Supported Providers​

    Wasp supports automated deployment to the following providers:

    • Fly.io - they offer 5$ free credit each month
    • Railway (coming soon, track it here #1157)

    Fly.io​

    Prerequisites​

    Fly provides free allowances for up to 3 VMs (so deploying a Wasp app to a new account is free), but all plans require you to add your credit card information before you can proceed. If you don't, the deployment will fail.

    You can add the required credit card information on the account's billing page.

    Fly.io CLI

    You will need the flyctl CLI installed on your machine before you can deploy to Fly.io.

    Deploying​

    Using the Wasp CLI, you can easily deploy a new app to Fly.io with just a single command:

    wasp deploy fly launch my-wasp-app mia
    Specifying Org

    If your account is a member of more than one organization on Fly.io, you will need to specify under which one you want to execute the command. To do that, provide an additional --org <org-slug> option. You can find out the names(slugs) of your organizations by running fly orgs list.

    Please do not CTRL-C or exit your terminal while the commands are running.

    Under the covers, this runs the equivalent of the following commands:

    wasp deploy fly setup my-wasp-app mia
    wasp deploy fly create-db mia
    wasp deploy fly deploy

    The commands above use the app basename my-wasp-app and deploy it to the Miami, Florida (US) region (called mia). Read more about Fly.io regions here.

    Unique Name

    Your app name must be unique across all of Fly or deployment will fail.

    The basename is used to create all three app tiers, resulting in three separate apps in your Fly dashboard:

    • my-wasp-app-client
    • my-wasp-app-server
    • my-wasp-app-db

    You'll notice that Wasp creates two new files in your project root directory:

    • fly-server.toml
    • fly-client.toml

    You should include these files in your version control so that you can deploy your app with a single command in the future.

    Using a Custom Domain For Your App​

    Setting up a custom domain is a three-step process:

    1. You need to add your domain to your Fly client app. You can do this by running:
    wasp deploy fly cmd --context client certs create mycoolapp.com
    Use Your Domain

    Make sure to replace mycoolapp.com with your domain in all of the commands mentioned in this section.

    This command will output the instructions to add the DNS records to your domain. It will look something like this:

    You can direct traffic to mycoolapp.com by:

    1: Adding an A record to your DNS service which reads

        A @ 66.241.1XX.154

    You can validate your ownership of mycoolapp.com by:

    2: Adding an AAAA record to your DNS service which reads:

        AAAA @ 2a09:82XX:1::1:ff40

    1. You need to add the DNS records for your domain:

      This will depend on your domain provider, but it should be a matter of adding an A record for @ and an AAAA record for @ with the values provided by the previous command.

    2. You need to set your domain as the WASP_WEB_CLIENT_URL environment variable for your server app:

    wasp deploy fly cmd --context server secrets set WASP_WEB_CLIENT_URL=https://mycoolapp.com

    We need to do this to keep our CORS configuration up to date.

    That's it, your app should be available at https://mycoolapp.com! 🎉

    API Reference​

    launch​

    launch is a convenience command that runs setup, create-db, and deploy in sequence.

    wasp deploy fly launch <app-name> <region>

    It accepts the following arguments:

    • <app-name> - the name of your app required

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    It gives you the same result as running the following commands:

    wasp deploy fly setup <app-name> <region>
    wasp deploy fly create-db <region>
    wasp deploy fly deploy

    Environment Variables​

    If you are deploying an app that requires any other environment variables (like social auth secrets), you can set them with the --server-secret option:

    wasp deploy fly launch my-wasp-app mia --server-secret GOOGLE_CLIENT_ID=<...> --server-secret GOOGLE_CLIENT_SECRET=<...>

    setup​

    setup will create your client and server apps on Fly, and add some secrets, but does not deploy them.

    wasp deploy fly setup <app-name> <region>

    It accepts the following arguments:

    • <app-name> - the name of your app required

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    After running setup, Wasp creates two new files in your project root directory: fly-server.toml and fly-client.toml. You should include these files in your version control.

    You can edit the fly-server.toml and fly-client.toml files to further configure your Fly deployments. Wasp will use the TOML files when you run deploy.

    If you want to maintain multiple apps, you can add the --fly-toml-dir <abs-path> option to point to different directories, like "dev" or "staging".

    Execute Only Once

    You should only run setup once per app. If you run it multiple times, it will create unnecessary apps on Fly.

    create-db​

    create-db will create a new database for your app.

    wasp deploy fly create-db <region>

    It accepts the following arguments:

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    Execute Only Once

    You should only run create-db once per app. If you run it multiple times, it will create multiple databases, but your app needs only one.

    deploy​

    wasp deploy fly deploy

    deploy pushes your client and server live.

    Run this command whenever you want to update your deployed app with the latest changes:

    wasp deploy fly deploy

    cmd​

    If want to run arbitrary Fly commands (e.g. flyctl secrets list for your server app), here's how to do it:

    wasp deploy fly cmd secrets list --context server

    Fly.io Regions​

    Fly.io runs applications physically close to users: in datacenters around the world, on servers we run ourselves. You can currently deploy your apps in 34 regions, connected to a global Anycast network that makes sure your users hit our nearest server, whether they’re in Tokyo, São Paolo, or Frankfurt.

    Read more on Fly regions here.

    You can find the list of all available Fly regions by running:

    flyctl platform regions

    Environment Variables​

    If you are deploying an app that requires any other environment variables (like social auth secrets), you can set them with the secrets set command:

    wasp deploy fly cmd secrets set GOOGLE_CLIENT_ID=<...> GOOGLE_CLIENT_SECRET=<...> --context=server

    Multiple Fly Organizations​

    If you have multiple organizations, you can specify a --org option. For example:

    wasp deploy fly launch my-wasp-app mia --org hive

    Building Locally​

    Fly.io offers support for both locally built Docker containers and remotely built ones. However, for simplicity and reproducibility, the CLI defaults to the use of a remote Fly.io builder.

    If you want to build locally, supply the --build-locally option to wasp deploy fly launch or wasp deploy fly deploy.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/advanced/deployment/manually.html b/docs/0.12.0/advanced/deployment/manually.html index d3f5f17241..6dd1aa4919 100644 --- a/docs/0.12.0/advanced/deployment/manually.html +++ b/docs/0.12.0/advanced/deployment/manually.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -39,7 +39,7 @@ Set it to a random string at least 32 characters long (you can use an online generator).

  • PORT

    The server's HTTP port number. This is where the server listens for requests (default: 3001).

    • 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 fa5fcad190..4f6837d924 100644 --- a/docs/0.12.0/advanced/deployment/overview.html +++ b/docs/0.12.0/advanced/deployment/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ 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 5fa02dce2c..6936631a51 100644 --- a/docs/0.12.0/advanced/email.html +++ b/docs/0.12.0/advanced/email.html @@ -18,14 +18,14 @@ - - - + + +
    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 d8619ca4e4..11e770cd63 100644 --- a/docs/0.12.0/advanced/jobs.html +++ b/docs/0.12.0/advanced/jobs.html @@ -18,14 +18,14 @@ - - - + + +
    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 190ba7af24..55658e2077 100644 --- a/docs/0.12.0/advanced/links.html +++ b/docs/0.12.0/advanced/links.html @@ -18,14 +18,14 @@ - - - + + +
    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 535d1b173e..d7da862023 100644 --- a/docs/0.12.0/advanced/middleware-config.html +++ b/docs/0.12.0/advanced/middleware-config.html @@ -18,14 +18,14 @@ - - - + + +
    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 87e0809de2..40662519f2 100644 --- a/docs/0.12.0/advanced/web-sockets.html +++ b/docs/0.12.0/advanced/web-sockets.html @@ -18,14 +18,14 @@ - - - + + +
    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 683434001a..a355978d14 100644 --- a/docs/0.12.0/auth/email.html +++ b/docs/0.12.0/auth/email.html @@ -18,14 +18,14 @@ - - - + + +
    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 4523b9824e..aba7e59e98 100644 --- a/docs/0.12.0/auth/entities.html +++ b/docs/0.12.0/auth/entities.html @@ -18,14 +18,14 @@ - - - + + +
    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 eee87b1b56..cd96030859 100644 --- a/docs/0.12.0/auth/overview.html +++ b/docs/0.12.0/auth/overview.html @@ -18,16 +18,16 @@ - - - + + +
    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

    Discord »

    Users sign in with their Discord 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",
      }
    }

    //...

    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

    Discord »

    Users sign in with their Discord 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 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 af70c0d903..c6da3f5f8f 100644 --- a/docs/0.12.0/auth/social-auth/github.html +++ b/docs/0.12.0/auth/social-auth/github.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ 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 b2e1f7a2ba..a0f30282da 100644 --- a/docs/0.12.0/auth/social-auth/google.html +++ b/docs/0.12.0/auth/social-auth/google.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ 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 9292a1ffb4..df28f27c7a 100644 --- a/docs/0.12.0/auth/social-auth/overview.html +++ b/docs/0.12.0/auth/social-auth/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -31,7 +31,7 @@ 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 6526b5703c..ddc54d39e1 100644 --- a/docs/0.12.0/auth/ui.html +++ b/docs/0.12.0/auth/ui.html @@ -18,14 +18,14 @@ - - - + + +
    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 050c84300d..7f98036cc3 100644 --- a/docs/0.12.0/auth/username-and-pass.html +++ b/docs/0.12.0/auth/username-and-pass.html @@ -18,14 +18,14 @@ - - - + + +
    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 6c4f6d6f03..5861c8d9e9 100644 --- a/docs/0.12.0/contact.html +++ b/docs/0.12.0/contact.html @@ -18,14 +18,14 @@ - - - + + +
    - - + + \ No newline at end of file diff --git a/docs/0.12.0/contributing.html b/docs/0.12.0/contributing.html index 486d9e7690..ac32d30ffa 100644 --- a/docs/0.12.0/contributing.html +++ b/docs/0.12.0/contributing.html @@ -18,14 +18,14 @@ - - - + + +
    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 52fe692999..6846487955 100644 --- a/docs/0.12.0/data-model/backends.html +++ b/docs/0.12.0/data-model/backends.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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 b975da2989..59ddba8c82 100644 --- a/docs/0.12.0/data-model/crud.html +++ b/docs/0.12.0/data-model/crud.html @@ -18,16 +18,16 @@ - - - + + +
    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 b72383d40d..d59e7a4fa8 100644 --- a/docs/0.12.0/data-model/entities.html +++ b/docs/0.12.0/data-model/entities.html @@ -18,16 +18,16 @@ - - - + + +
    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 5cfa2ce05a..9b59fa9aa9 100644 --- a/docs/0.12.0/data-model/operations/actions.html +++ b/docs/0.12.0/data-model/operations/actions.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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 1f3a953bed..41c7e5c52f 100644 --- a/docs/0.12.0/data-model/operations/overview.html +++ b/docs/0.12.0/data-model/operations/overview.html @@ -18,15 +18,15 @@ - - - + + +
    - - + + \ 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 3b32f8eef8..874373fa98 100644 --- a/docs/0.12.0/data-model/operations/queries.html +++ b/docs/0.12.0/data-model/operations/queries.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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 68053c771c..ac92d9fc78 100644 --- a/docs/0.12.0/editor-setup.html +++ b/docs/0.12.0/editor-setup.html @@ -18,14 +18,14 @@ - - - + + +
    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 5f7de5e9e6..c047e5a777 100644 --- a/docs/0.12.0/general/cli.html +++ b/docs/0.12.0/general/cli.html @@ -18,14 +18,14 @@ - - - + + +
    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 e0e23f2106..8122d35078 100644 --- a/docs/0.12.0/general/language.html +++ b/docs/0.12.0/general/language.html @@ -18,16 +18,16 @@ - - - + + +
    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 a6360f6e9f..a83bb125c3 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 @@ -18,9 +18,9 @@ - - - + + +
    @@ -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 19371807ba..2b2f7561d9 100644 --- a/docs/0.12.0/project/client-config.html +++ b/docs/0.12.0/project/client-config.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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 5cfeb861a3..a9269be2bc 100644 --- a/docs/0.12.0/project/css-frameworks.html +++ b/docs/0.12.0/project/css-frameworks.html @@ -18,14 +18,14 @@ - - - + + +
    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 7b85593172..c0f334eabb 100644 --- a/docs/0.12.0/project/custom-vite-config.html +++ b/docs/0.12.0/project/custom-vite-config.html @@ -18,14 +18,14 @@ - - - + + +
    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 1173b3883a..773badaca9 100644 --- a/docs/0.12.0/project/customizing-app.html +++ b/docs/0.12.0/project/customizing-app.html @@ -18,15 +18,15 @@ - - - + + +
    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:

    • wasp: dict required Wasp compiler configuration. It is a dictionary with a single field:

      • version: string required

        The version specifies which versions of Wasp are compatible with the app. It should contain a valid SemVer range

        info

        For now, the version field only supports caret ranges (i.e., ^x.y.z). Support for the full specification will come in a future version of Wasp

    • title: string required

      Title of your app. It will appear in the browser tab, next to the favicon.

    • head: [string]

      List of additional lines (e.g. <link> or <script> tags) to be included in the <head> of your HTML document.

    The rest of the fields are covered in dedicated sections of the docs:

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/project/dependencies.html b/docs/0.12.0/project/dependencies.html index 4e059039dd..8c187a0b40 100644 --- a/docs/0.12.0/project/dependencies.html +++ b/docs/0.12.0/project/dependencies.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.12.0

    Dependencies

    In a Wasp project, dependencies are defined in a standard way for JavaScript projects: using the package.json file, located at the root of your project. You can list your dependencies under the dependencies or devDependencies fields.

    Adding a New Dependency​

    To add a new package, like date-fns (a great date handling library), you use npm:

    npm install date-fns

    This command will add the package in the dependencies section of your package.json file.

    You will notice that there are some other packages in the dependencies section, like react and wasp. These are the packages that Wasp uses internally, and you should not modify or remove them.

    Using Packages that are Already Used by Wasp Internally​

    In the current version of Wasp, if Wasp is already internally using a certain dependency (e.g. React) with a certain version specified, you are not allowed to define that same npm dependency yourself while specifying a different version.

    If you do that, you will get an error message telling you which exact version you have to use for that dependency. This means Wasp dictates exact versions of certain packages, so for example you can't choose the version of React you want to use.

    note

    We are currently working on a restructuring that will solve this and some other quirks: check issue #734 to follow our progress.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/project/env-vars.html b/docs/0.12.0/project/env-vars.html index 3b904cb91a..d070f07186 100644 --- a/docs/0.12.0/project/env-vars.html +++ b/docs/0.12.0/project/env-vars.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.12.0

    Env Variables

    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.

    For instance, during development, you may want your project to connect to a local development database running on your machine, but 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.

    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.

    In Wasp, you can use environment variables in both the client and the server code.

    Client Env Vars​

    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 never store secrets in them (such as secret API keys).

    To enable Wasp to pick them up, client environment variables must be prefixed with REACT_APP_, for example: REACT_APP_SOME_VAR_NAME=....

    You can read them from the client code like this:

    src/App.js
    console.log(import.meta.env.REACT_APP_SOME_VAR_NAME)

    Check below on how to define them.

    Server Env Vars​

    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 SOME_VAR_NAME=....

    You can read them in the server code like this:

    console.log(process.env.SOME_VAR_NAME)

    Check below on how to define them.

    Defining Env Vars in Development​

    During development, there are two ways to provide env vars to your Wasp project:

    1. Using .env files. (recommended)
    2. Using shell. (useful for overrides)

    1. Using .env (dotenv) Files​

    Env vars usage in development

    This is the recommended method for providing env vars to your Wasp project during development.

    In the root of your Wasp project you can create two distinct files:

    • .env.server for env vars that will be provided to the server.

      Variables are defined in these files in the form of NAME=VALUE, for example:

      .env.server
      DATABASE_URL=postgresql://localhost:5432
      SOME_VAR_NAME=somevalue

    • .env.client for env vars that will be provided to the client.

      Variables are defined in these files in the form of NAME=VALUE, for example:

      .env.client
      REACT_APP_SOME_VAR_NAME=somevalue

    These files should not be committed to version control, and they are already ignored by default in the .gitignore file that comes with Wasp.

    2. Using Shell​

    If you set environment variables in the shell where you run your Wasp commands (e.g., wasp start), Wasp will recognize them.

    You can set environment variables in the .profile or a similar file, or by defining them at the start of a command:

    SOME_VAR_NAME=SOMEVALUE wasp start

    This is not specific to Wasp and is simply how environment variables can be set in the shell.

    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 overriding specific environment variables because environment variables set this way take precedence over those defined in .env files.

    Defining Env Vars in Production​

    While in development, we had the option of using .env files which made it easy to define and manage env vars. However, in production, we need to provide env vars differently.

    Env vars usage in development and production

    Client Env Vars​

    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 never store secrets in them (such as secret API keys).

    You should provide them to the build command, for example:

    REACT_APP_SOME_VAR_NAME=somevalue npm run build
    How it works

    What happens behind the scenes is that Wasp will replace all occurrences of 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.

    Read more about it in Vite's docs.

    Server Env Vars​

    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 Fly, you can define them using the flyctl CLI tool:

    flyctl secrets set SOME_VAR_NAME=somevalue

    You can read a lot more details in the deployment section of the docs. We go into detail on how to define env vars for each deployment option.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/project/server-config.html b/docs/0.12.0/project/server-config.html index 86d80d65b0..3402d7616a 100644 --- a/docs/0.12.0/project/server-config.html +++ b/docs/0.12.0/project/server-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.12.0

    Server Config

    You can configure the behavior of the server via the server field of app declaration:

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      server: {
        setupFn: import { mySetupFunction } from "@src/myServerSetupCode.js",
        middlewareConfigFn: import { myMiddlewareConfigFn } from "@src/myServerSetupCode.js"
      }
    }

    Setup Function​

    Adding a Custom Route​

    As an example, adding a custom route would look something like:

    src/myServerSetupCode.ts
    export const mySetupFunction = async ({ app }) => {
      addCustomRoute(app)
    }

    function addCustomRoute(app) {
      app.get('/customRoute', (_req, res) => {
        res.send('I am a custom route')
      })
    }

    Storing Some Values for Later Use​

    In case you want to store some values for later use, or to be accessed by the Operations you do that in the setupFn function.

    Dummy example of such function and its usage:

    src/myServerSetupCode.js
    let someResource = undefined

    export const mySetupFunction = async () => {
      // Let's pretend functions setUpSomeResource and startSomeCronJob
      // are implemented below or imported from another file.
      someResource = await setUpSomeResource()
      startSomeCronJob()
    }

    export const getSomeResource = () => someResource
    src/queries.js
    import { getSomeResource } from './myServerSetupCode.js'

    ...

    export const someQuery = async (args, context) => {
      const someResource = getSomeResource()
      return queryDataFromSomeResource(args, someResource)
    }
    note

    The recommended way is to put the variable in the same module where you defined the setup function and then expose additional functions for reading those values, which you can then import directly from Operations and use.

    This effectively turns your module into a singleton whose construction is performed on server start.

    Read more about server setup function below.

    Middleware Config Function​

    You can configure the global middleware via the middlewareConfigFn. This will modify the middleware stack for all operations and APIs.

    Read more about middleware config function below.

    API Reference​

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      server: {
        setupFn: import { mySetupFunction } from "@src/myServerSetupCode.js",
        middlewareConfigFn: import { myMiddlewareConfigFn } from "@src/myServerSetupCode.js"
      }
    }

    app.server is a dictionary with the following fields:

    • setupFn: ExtImport​

      setupFn declares a function that will be executed on server start. This function is expected to be async and will be awaited before the server starts accepting any requests.

      It allows you to do any custom setup, e.g. setting up additional database/websockets or starting cron/scheduled jobs.

      The setupFn function receives the express.Application and the http.Server instances as part of its context. They can be useful for setting up any custom server logic.

      src/myServerSetupCode.js
      export const mySetupFunction = async () => {
        await setUpSomeResource()
      }

    • middlewareConfigFn: ExtImport​

      The import statement to an Express middleware config function. This is a global modification affecting all operations and APIs. See more in the configuring middleware section.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/project/starter-templates.html b/docs/0.12.0/project/starter-templates.html index 6d79d67ba4..76b6abf057 100644 --- a/docs/0.12.0/project/starter-templates.html +++ b/docs/0.12.0/project/starter-templates.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.12.0

    Starter Templates

    We created a few starter templates to help you get started with Wasp. Check out the list below.

    Using a Template​

    Run wasp new to run the interactive mode for creating a new Wasp project.

    It will ask you for the project name, and then for the template to use:

    $ 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

    Available Templates​

    When you have a good idea for a new product, you don't want to waste your time on setting up common things like authentication, database, etc. That's why we created a few starter templates to help you get started with Wasp.

    OpenSaaS.sh template​

    SaaS Template

    Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check out https://opensaas.sh/ for more details.

    Features: Stripe Payments, OpenAI GPT API, Google Auth, SendGrid, Tailwind, & Cron Jobs

    Use this template:

    wasp new <project-name> -t saas

    Vector Similarity Search Template​

    Vector Similarity Search Template

    A template for generating embeddings and performing vector similarity search on your text data!

    Features: Embeddings & vector similarity search, OpenAI Embeddings API, Vector DB (Pinecone), Tailwind, Fullstack Type Safety

    Use this template:

    wasp new <project-name> -t embeddings

    Todo App w/ Typescript​

    A simple Todo App with Typescript and Fullstack Type Safety.

    Features: Auth (username/password), Fullstack Type Safety

    Use this template:

    wasp new <project-name> -t todo-ts

    AI Generated Starter 🤖​

    Using the same tech as used on https://usemage.ai/, Wasp generates your custom starter template based on your project description. It will automatically generate your data model, auth, queries, actions and React pages.

    You will need to provide your own OpenAI API key to be able to use this template.

    Features: Generated using OpenAI's GPT models, Auth (username/password), Queries, Actions, Pages, Fullstack Type Safety

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/project/static-assets.html b/docs/0.12.0/project/static-assets.html index f6c08fcada..a9bc2a9fd3 100644 --- a/docs/0.12.0/project/static-assets.html +++ b/docs/0.12.0/project/static-assets.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.12.0

    Static Asset Handling

    Importing an Asset as URL​

    Importing a static asset (e.g. an image) will return its URL. For example:

    src/App.jsx
    import imgUrl from './img.png'

    function App() {
      return <img src={imgUrl} alt="img" />
    }

    For example, imgUrl will be /img.png during development, and become /assets/img.2d8efhg.png in the production build.

    This is what you want to use most of the time, as it ensures that the asset file exists and is included in the bundle.

    We are using Vite under the hood, read more about importing static assets in Vite's docs.

    The public Directory​

    If you have assets that are:

    • Never referenced in source code (e.g. robots.txt)
    • Must retain the exact same file name (without hashing)
    • ...or you simply don't want to have to import an asset first just to get its URL

    Then you can place the asset in the public directory at the root of your project:

    .
    └── public
        ├── favicon.ico
        └── robots.txt

    Assets in this directory will be served at root path / during development and copied to the root of the dist directory as-is.

    For example, if you have a file favicon.ico in the public directory, and your app is hosted at https://myapp.com, it will be made available at https://myapp.com/favicon.ico.

    Usage in client code

    Note that:

    • You should always reference public assets using root absolute path
      • for example, public/icon.png should be referenced in source code as /icon.png.
    • Assets in the public directory cannot be imported from .
    - - + + \ No newline at end of file diff --git a/docs/0.12.0/project/testing.html b/docs/0.12.0/project/testing.html index 249558721a..8559cd26b6 100644 --- a/docs/0.12.0/project/testing.html +++ b/docs/0.12.0/project/testing.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.12.0

    Testing

    info

    Wasp is in beta, so keep in mind there might be some kinks / bugs, and possibly some changes with testing support in the future. If you encounter any issues, reach out to us on Discord and we will make sure to help you out!

    Testing Your React App​

    Wasp enables you to quickly and easily write both unit tests and React component tests for your frontend code. Because Wasp uses Vite, we support testing web apps through Vitest.

    Included Libraries

    vitest: Unit test framework with native Vite support.

    @vitest/ui: A nice UI for seeing your test results.

    jsdom: A web browser test environment for Node.js.

    @testing-library/react / @testing-library/jest-dom: Testing helpers.

    msw: A server mocking library.

    Writing Tests​

    For Wasp to pick up your tests, they should be placed within the src directory and use an extension that matches these glob patterns. Some of the file names that Wasp will pick up as tests:

    • yourFile.test.ts
    • YourComponent.spec.jsx

    Within test files, you can import your other source files as usual. For example, if you have a component Counter.jsx, you test it by creating a file in the same directory called Counter.test.jsx and import the component with import Counter from './Counter'.

    Running Tests​

    Running wasp test client will start Vitest in watch mode and recompile your Wasp project when changes are made.

    • If you want to see a realtime UI, pass --ui as an option.
    • To run the tests just once, use wasp test client run.

    All arguments after wasp test client are passed directly to the Vitest CLI, so check out their documentation for all of the options.

    Be Careful

    You should not run wasp test while wasp start is running. Both will try to compile your project to .wasp/out.

    React Testing Helpers​

    Wasp provides several functions to help you write React tests:

    • renderInContext: Takes a React component, wraps it inside a QueryClientProvider and Router, and renders it. This is the function you should use to render components in your React component tests.

      import { renderInContext } from "wasp/client/test";

      renderInContext(<MainPage />);

    • mockServer: Sets up the mock server and returns an object containing the mockQuery and mockApi utilities. This should be called outside of any test case, in each file that wants to use those helpers.

      import { mockServer } from "wasp/client/test";

      const { mockQuery, mockApi } = mockServer();

      • mockQuery: Takes a Wasp query to mock and the JSON data it should return.

        import { getTasks } from "wasp/client/operations";

        mockQuery(getTasks, []);
        • Helpful when your component uses useQuery.
        • Behind the scenes, Wasp uses msw to create a server request handle that responds with the specified data.
        • Mock are cleared between each test.

      • mockApi: Similar to mockQuery, but for APIs. Instead of a Wasp query, it takes a route containing an HTTP method and a path.

        import { HttpMethod } from "wasp/client";

        mockApi({ method: HttpMethod.Get, path: "/foor/bar" }, { res: "hello" });

    Testing Your Server-Side Code​

    Wasp currently does not provide a way to test your server-side code, but we will be adding support soon. You can track the progress at this GitHub issue and express your interest by commenting.

    Examples​

    You can see some tests in a Wasp project here.

    Client Unit Tests​

    src/helpers.js
    export function areThereAnyTasks(tasks) {
      return tasks.length === 0;
    }
    src/helpers.test.js
    import { test, expect } from "vitest";

    import { areThereAnyTasks } from "./helpers";

    test("areThereAnyTasks", () => {
      expect(areThereAnyTasks([])).toBe(false);
    });

    React Component Tests​

    src/Todo.jsx
    import { useQuery, getTasks } from "wasp/client/operations";

    const Todo = (_props) => {
      const { data: tasks } = useQuery(getTasks);
      return (
        <ul>
          {tasks &&
            tasks.map((task) => (
              <li key={task.id}>
                <input type="checkbox" value={task.isDone} />
                {task.description}
              </li>
            ))}
        </ul>
      );
    };
    src/Todo.test.jsx
    import { test, expect } from "vitest";
    import { screen } from "@testing-library/react";

    import { mockServer, renderInContext } from "wasp/client/test";
    import { getTasks } from "wasp/client/operations";
    import Todo from "./Todo";

    const { mockQuery } = mockServer();

    const mockTasks = [
      {
        id: 1,
        description: "test todo 1",
        isDone: true,
        userId: 1,
      },
    ];

    test("handles mock data", async () => {
      mockQuery(getTasks, mockTasks);

      renderInContext(<Todo />);

      await screen.findByText("test todo 1");

      expect(screen.getByRole("checkbox")).toBeChecked();

      screen.debug();
    });

    Testing With Mocked APIs​

    src/Todo.jsx
    import { api } from "wasp/client/api";

    const Todo = (_props) => {
      const [tasks, setTasks] = useState([]);
      useEffect(() => {
        api
          .get("/tasks")
          .then((res) => res.json())
          .then((tasks) => setTasks(tasks))
          .catch((err) => window.alert(err));
      });

      return (
        <ul>
          {tasks &&
            tasks.map((task) => (
              <li key={task.id}>
                <input type="checkbox" value={task.isDone} />
                {task.description}
              </li>
            ))}
        </ul>
      );
    };
    src/Todo.test.jsx
    import { test, expect } from "vitest";
    import { screen } from "@testing-library/react";

    import { mockServer, renderInContext } from "wasp/client/test";
    import Todo from "./Todo";

    const { mockApi } = mockServer();

    const mockTasks = [
      {
        id: 1,
        description: "test todo 1",
        isDone: true,
        userId: 1,
      },
    ];

    test("handles mock data", async () => {
      mockApi("/tasks", { res: mockTasks });

      renderInContext(<Todo />);

      await screen.findByText("test todo 1");

      expect(screen.getByRole("checkbox")).toBeChecked();

      screen.debug();
    });
    - - + + \ No newline at end of file diff --git a/docs/0.12.0/quick-start.html b/docs/0.12.0/quick-start.html index 62a52736fc..b2079c8463 100644 --- a/docs/0.12.0/quick-start.html +++ b/docs/0.12.0/quick-start.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.12.0

    Quick Start

    Installation​

    Welcome, new Waspeteer 🐝!

    Let's create and run our first Wasp app in 3 short steps:

    1. To install Wasp on Linux / OSX / WSL (Windows), open your terminal and run:

      curl -sSL https://get.wasp-lang.dev/installer.sh | sh

      ℹ️ Wasp requires Node.js and will warn you if it is missing: check below for more details.

    2. Then, create a new app by running:

      wasp new

    3. Finally, run the app:

      cd <my-project-name>
      wasp start

    That's it 🎉 You have successfully created and served a new full-stack web app at http://localhost:3000 and Wasp is serving both frontend and backend for you.

    Something Unclear?

    Check More Details section below if anything went wrong with the installation, or if you have additional questions.

    Want an even faster start?

    Try out Wasp AI 🤖 to generate a new Wasp app in minutes just from a title and short description!

    Try Wasp Without Installing 🤔?

    Give Wasp a spin in the browser without any setup by running our Wasp Template for Gitpod

    What next?​

    • 👉 Check out the Todo App tutorial, which will take you through all the core features of Wasp! 👈
    • Setup your editor for working with Wasp.
    • Join us on Discord! Any feedback or questions you have, we are there for you.
    • Follow Wasp development by subscribing to our newsletter: https://wasp-lang.dev/#signup . We usually send 1 per month, and Matija does his best to unleash his creativity to make them engaging and fun to read :D!

    More details​

    Requirements​

    You must have Node.js (and NPM) installed on your machine and available in PATH. A version of Node.js must be >= 18.

    If you need it, we recommend using nvm for managing your Node.js installation version(s).

    A quick guide on installing/using nvm

    Install nvm via your OS package manager (apt, pacman, homebrew, ...) or via the nvm install script.

    Then, install a version of Node.js that you need:

    nvm install 20

    Finally, whenever you need to ensure a specific version of Node.js is used, run:

    nvm use 20

    to set the Node.js version for the current shell session.

    You can run

    node -v

    to check the version of Node.js currently being used in this shell session.

    Check NVM repo for more details: https://github.com/nvm-sh/nvm.

    Installation​

    Open your terminal and run:

    curl -sSL https://get.wasp-lang.dev/installer.sh | sh
    Running Wasp on Mac with Mx chip (arm64)

    Experiencing the 'Bad CPU type in executable' issue on a device with arm64 (Apple Silicon)? Given that the wasp binary is built for x86 and not for arm64 (Apple Silicon), you'll need to install Rosetta on your Mac if you are using a Mac with Mx (M1, M2, ...). Rosetta is a translation process that enables users to run applications designed for x86 on arm64 (Apple Silicon). To install Rosetta, run the following command in your terminal

    softwareupdate --install-rosetta

    Once Rosetta is installed, you should be able to run Wasp without any issues.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/telemetry.html b/docs/0.12.0/telemetry.html index ec5524749a..f829a7a475 100644 --- a/docs/0.12.0/telemetry.html +++ b/docs/0.12.0/telemetry.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.12.0

    Telemetry

    Overview​

    The term telemetry refers to the collection of certain usage data to help improve the quality of a piece of software (in this case, Wasp).

    Our telemetry implementation is anonymized and very limited in its scope, focused on answering following questions:

    • How many people and how often: tried to install Wasp, use Wasp, have built a Wasp app, or have deployed one?
    • How many projects are created with Wasp?

    When and what is sent?​

    • Information is sent via HTTPS request when wasp CLI command is invoked. Information is sent no more than twice in a period of 12 hours (sending is paused for 12 hours after last invocation, separately for wasp build command and for all other commands). Exact information as it is sent:
      {
        // Randomly generated, non-identifiable UUID representing a user.
        "distinct_id": "bf3fa7a8-1c11-4f82-9542-ec1a2d28786b",
        // Non-identifiable hash representing a project.
        "project_hash": "6d7e561d62b955d1",
        // True if command was `wasp build`, false otherwise.
        "is_build": true,
        // Captures `wasp deploy ...` args, but only those from the limited, pre-defined list of keywords.
        // Those are "fly", "setup", "create-db", "deploy" and "cmd". Everything else is ommited.
        "deploy_cmd_args": "fly;deploy",
        "wasp_version": "0.1.9.1",
        "os": "linux",
        // "CI" if running on CI, and whatever is the content of "WASP_TELEMETRY_CONTEXT" env var.
        // We use this to track when execution is happening in some special context, like on Gitpod, Replit or similar.
        "context": "CI"
      }
    • Information is also sent once via HTTPS request when wasp is installed via install.sh script. Exact information as it is sent:
      {
        // Randomly generated id.
        "distinct_id": "274701613078193779564259",
        "os": "linux"
      }

    Opting out​

    You sharing the telemetry data with us means a lot to us, since it helps us understand how popular Wasp is, how it is being used, how the changes we are doing affect usage, how many new vs old users there are, and just in general how Wasp is doing. We look at these numbers every morning and they drive us to make Wasp better.

    However, if you wish to opt-out of telemetry, we understand! You can do so by setting the WASP_TELEMETRY_DISABLE environment variable to any value, e.g.:

    export WASP_TELEMETRY_DISABLE=1

    Future plans​

    We don't have this implemented yet, but the next step will be to make telemetry go in two directions -> instead of just sending usage data to us, it will also at the same time check for any messages from our side (e.g. notification about new version of Wasp, or a security notice). Link to corresponding github issue.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/tutorial/actions.html b/docs/0.12.0/tutorial/actions.html index c51d21f2ed..a15e20fec4 100644 --- a/docs/0.12.0/tutorial/actions.html +++ b/docs/0.12.0/tutorial/actions.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.12.0

    6. Modifying Data

    In the previous section, we learned about using Queries to fetch data and only briefly mentioned that Actions can be used to update the database. Let's learn more about Actions so we can add and update tasks in the database.

    We have to create:

    1. A Wasp Action that creates a new task.
    2. A React form that calls that Action when the user creates a task.

    Creating a New Action​

    Creating an Action is very similar to creating a Query.

    Declaring an Action​

    We must first declare the Action in main.wasp:

    main.wasp
    // ...

    action createTask {
      fn: import { createTask } from "@src/actions",
      entities: [Task]
    }

    Implementing an Action​

    Let's now define a function for our createTask Action:

    src/actions.js
    export const createTask = async (args, context) => {
      return context.entities.Task.create({
        data: { description: args.description },
      })
    }
    tip

    We put the function in a new file src/actions.ts, but we could have put it anywhere we wanted! There are no limitations here, as long as the declaration in the Wasp file imports it correctly and the file is located within src directory.

    Invoking the Action on the Client​

    Start by defining a form for creating new tasks.

    src/MainPage.jsx
    import { 
      createTask, 
      getTasks, 
      useQuery 
    } from 'wasp/client/operations'

    // ... MainPage, TaskView, TaskList ...

    const NewTaskForm = () => {
      const handleSubmit = async (event) => {
        event.preventDefault()
        try {
          const target = event.target
          const description = target.description.value
          target.reset()
          await createTask({ description })
        } catch (err) {
          window.alert('Error: ' + err.message)
        }
      }

      return (
        <form onSubmit={handleSubmit}>
          <input name="description" type="text" defaultValue="" />
          <input type="submit" value="Create task" />
        </form>
      )
    }

    Unlike Queries, you can call Actions directly (i.e., without wrapping it with a hook) because we don't need reactivity. The rest is just regular React code.

    All that's left now is adding this form to the page component:

    src/MainPage.jsx
    import {
      createTask,
      getTasks,
      useQuery
    } from 'wasp/client/operations'

    const MainPage = () => {
      const { data: tasks, isLoading, error } = useQuery(getTasks)

      return (
        <div>
          <NewTaskForm />

          {tasks && <TasksList tasks={tasks} />}

          {isLoading && 'Loading...'}
          {error && 'Error: ' + error}
        </div>
      )
    }

    // ... TaskView, TaskList, NewTaskForm ...

    Great work!

    You now have a form for creating new tasks.

    Try creating a "Build a Todo App in Wasp" task and see it appear in the list below. The task is created on the server and saved in the database.

    Try refreshing the page or opening it in another browser. You'll see the tasks are still there!

    Todo App - creating new task

    Automatic Query Invalidation

    When you create a new task, the list of tasks is automatically updated to display the new task, even though we have not written any code that would do that! Wasp handles these automatic updates under the hood.

    When you declared the getTasks and createTask operations, you specified that they both use the Task entity. So when createTask is called, Wasp knows that the data getTasks fetches may have changed and automatically updates it in the background. This means that out of the box, Wasp keeps all your queries in sync with any changes made through Actions.

    This behavior is convenient as a default but can cause poor performance in large apps. While there is no mechanism for overriding this behavior yet, it is something that we plan to include in Wasp in the future. This feature is tracked here.

    A Second Action​

    Our Todo app isn't finished if you can't mark a task as done.

    We'll create a new Action to update a task's status and call it from React whenever a task's checkbox is toggled.

    Since we've already created one task together, try to create this one yourself. It should be an Action named updateTask that receives the task's id and its isDone status. You can see our implementation below.

    Solution

    Declaring the Action in main.wasp:

    main.wasp
    // ...

    action updateTask {
      fn: import { updateTask } from "@src/actions",
      entities: [Task]
    }

    Implementing the Action on the server:

    src/actions.js
    // ...

    export const updateTask = async ({ id, isDone }, context) => {
      return context.entities.Task.update({
        where: { id },
        data: {
          isDone: isDone,
        },
      })
    }

    You can now call updateTask from the React component:

    src/MainPage.jsx
    // ...
    import {
      updateTask,
      createTask,
      getTasks,
      useQuery,
    } from 'wasp/client/operations'

    // ... MainPage ...

    const TaskView = ({ task }) => {
      const handleIsDoneChange = async (event) => {
        try {
          await updateTask({
            id: task.id,
            isDone: event.target.checked,
          })
        } catch (error) {
          window.alert('Error while updating task: ' + error.message)
        }
      }

      return (
        <div>
          <input
            type="checkbox"
            id={String(task.id)}
            checked={task.isDone}
            onChange={handleIsDoneChange}
          />
          {task.description}
        </div>
      )
    }
    // ... TaskList, NewTaskForm ...

    Awesome! You can now mark this task as done.

    It's time to make one final addition to your app: supporting multiple users.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/tutorial/auth.html b/docs/0.12.0/tutorial/auth.html index 4611776dfb..ca7a4c2268 100644 --- a/docs/0.12.0/tutorial/auth.html +++ b/docs/0.12.0/tutorial/auth.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.12.0

    7. Adding Authentication

    Most modern apps need a way to create and authenticate users. Wasp makes this as easy as possible with its first-class auth support.

    To add users to your app, you must:

    • Create a User Entity.
    • Tell Wasp to use the Username and Password authentication.
    • Add login and signup pages.
    • Update the main page to require authentication.
    • Add a relation between User and Task entities.
    • Modify your Queries and Actions so users can only see and modify their tasks.
    • Add a logout button.

    Creating a User Entity​

    Since Wasp manages authentication, it will create the auth related entities for you in the background. Nothing to do here!

    You must only add the User Entity to keep track of who owns which tasks.

    main.wasp
    // ...

    entity User {=psl
        id       Int    @id @default(autoincrement())
    psl=}

    Adding Auth to the Project​

    Next, tell Wasp to use full-stack authentication:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.12.0"
      },
      title: "TodoApp",
      auth: {
        // Tells Wasp which entity to use for storing users.
        userEntity: User,
        methods: {
          // Enable username and password auth.
          usernameAndPassword: {}
        },
        // We'll see how this is used in a bit.
        onAuthFailedRedirectTo: "/login"
      }
    }

    // ...

    Don't forget to update the database schema by running:

    wasp db migrate-dev

    By doing this, Wasp will create:

    • Auth UI with login and signup forms.
    • A logout() action.
    • A React hook useAuth().
    • context.user for use in Queries and Actions.
    info

    Wasp also supports authentication using Google, GitHub, and email, with more on the way!

    Adding Login and Signup Pages​

    Wasp creates the login and signup forms for us, but we still need to define the pages to display those forms on. We'll start by declaring the pages in the Wasp file:

    main.wasp
    // ...

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage"
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage"
    }

    Great, Wasp now knows these pages exist!

    Here's the React code for the pages you've just imported:

    src/LoginPage.jsx
    import { Link } from 'react-router-dom'
    import { LoginForm } from 'wasp/client/auth'

    export const LoginPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <LoginForm />
          <br />
          <span>
            I don't have an account yet (<Link to="/signup">go to signup</Link>).
          </span>
        </div>
      )
    }

    The signup page is very similar to the login page:

    src/SignupPage.jsx
    import { Link } from 'react-router-dom'
    import { SignupForm } from 'wasp/client/auth'

    export const SignupPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <SignupForm />
          <br />
          <span>
            I already have an account (<Link to="/login">go to login</Link>).
          </span>
        </div>
      )
    }

    Update the Main Page to Require Auth​

    We don't want users who are not logged in to access the main page, because they won't be able to create any tasks. So let's make the page private by requiring the user to be logged in:

    main.wasp
    // ...

    page MainPage {
      authRequired: true,
      component: import { MainPage } from "@src/MainPage"
    }

    Now that auth is required for this page, unauthenticated users will be redirected to /login, as we specified with app.auth.onAuthFailedRedirectTo.

    Additionally, when authRequired is true, the page's React component will be provided a user object as prop.

    src/MainPage.jsx
    export const MainPage = ({ user }) => {
      // Do something with the user
      // ...
    }

    Ok, time to test this out. Navigate to the main page (/) of the app. You'll get redirected to /login, where you'll be asked to authenticate.

    Since we just added users, you don't have an account yet. Go to the signup page and create one. You'll be sent back to the main page where you will now be able to see the TODO list!

    Let's check out what the database looks like. Start the Prisma Studio:

    wasp db studio
    Database demonstration - password hashing

    You'll notice that we now have a User entity in the database alongside the Task entity.

    However, you will notice that if you try logging in as different users and creating some tasks, all users share the same tasks. That's because we haven't yet updated the queries and actions to have per-user tasks. Let's do that next.

    You might notice some extra Prisma models like Auth, AuthIdentity and Session that Wasp created for us. You don't need to care about these right now, but if you are curious, you can read more about them here.

    Defining a User-Task Relation​

    First, let's define a one-to-many relation between users and tasks (check the Prisma docs on relations):

    main.wasp
    // ...

    entity User {=psl
        id       Int    @id @default(autoincrement())
        tasks    Task[]
    psl=}

    entity Task {=psl
        id          Int     @id @default(autoincrement())
        description String
        isDone      Boolean @default(false)
        user        User?   @relation(fields: [userId], references: [id])
        userId      Int?
    psl=}

    // ...

    As always, you must migrate the database after changing the Entities:

    wasp db migrate-dev
    note

    We made user and userId in Task optional (via ?) because that allows us to keep the existing tasks, which don't have a user assigned, in the database.

    This isn't recommended because it allows an unwanted state in the database (what is the purpose of the task not belonging to anybody?) and normally we would not make these fields optional.

    Instead, we would do a data migration to take care of those tasks, even if it means just deleting them all. However, for this tutorial, for the sake of simplicity, we will stick with this.

    Updating Operations to Check Authentication​

    Next, let's update the queries and actions to forbid access to non-authenticated users and to operate only on the currently logged-in user's tasks:

    src/queries.js
    import { HttpError } from 'wasp/server'

    export const getTasks = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.findMany({
        where: { user: { id: context.user.id } },
        orderBy: { id: 'asc' },
      })
    }
    src/actions.js
    import { HttpError } from 'wasp/server'

    export const createTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.create({
        data: {
          description: args.description,
          user: { connect: { id: context.user.id } },
        },
      })
    }

    export const updateTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.updateMany({
        where: { id: args.id, user: { id: context.user.id } },
        data: { isDone: args.isDone },
      })
    }
    note

    Due to how Prisma works, we had to convert update to updateMany in updateTask action to be able to specify the user id in where.

    With these changes, each user should have a list of tasks that only they can see and edit.

    Try playing around, adding a few users and some tasks for each of them. Then open the DB studio:

    wasp db studio
    Database demonstration

    You will see that each user has their tasks, just as we specified in our code!

    Logout Button​

    Last, but not least, let's add the logout functionality:

    src/MainPage.jsx
    // ...
    import { logout } from 'wasp/client/auth'
    //...

    const MainPage = () => {
      // ...
      return (
        <div>
          // ...
          <button onClick={logout}>Logout</button>
        </div>
      )
    }

    This is it, we have a working authentication system, and our Todo app is multi-user!

    What's Next?​

    We did it 🎉 You've followed along with this tutorial to create a basic Todo app with Wasp.

    You should be ready to learn about more complicated features and go more in-depth with the features already covered. Scroll through the sidebar on the left side of the page to see every feature Wasp has to offer. Or, let your imagination run wild and start building your app! ✨

    Looking for inspiration?

    note

    If you notice that some of the features you'd like to have are missing, or have any other kind of feedback, please write to us on Discord or create an issue on Github, so we can learn which features to add/improve next 🙏

    If you would like to contribute or help to build a feature, let us know! You can find more details on contributing here.

    Oh, and do subscribe to our newsletter! We usually send one per month, and Matija does his best to unleash his creativity to make them engaging and fun to read :D!

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/tutorial/create.html b/docs/0.12.0/tutorial/create.html index 97cf3ce9df..c2761be759 100644 --- a/docs/0.12.0/tutorial/create.html +++ b/docs/0.12.0/tutorial/create.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.12.0

    1. Creating a New Project

    info

    You'll need to have the latest version of Wasp installed locally to follow this tutorial. If you haven't installed it yet, check out the QuickStart guide!

    In this section, we'll guide you through the process of creating a simple Todo app with Wasp. In the process, we'll take you through the most important and useful features of Wasp.

    How Todo App will work once it is done

    If you get stuck at any point (or just want to chat), reach out to us on Discord and we will help you!

    You can find the complete code of the app we're about to build here.

    Creating a Project​

    To setup a new Wasp project, run the following command in your terminal

    $ wasp new TodoApp

    Enter the newly created directory and start the development server:

    $ cd TodoApp
    $ wasp start
    note

    wasp start will take a bit of time to start the server the first time you run it in a new project.

    You will see log messages from the client, server, and database setting themselves up. When everything is ready, a new tab should open in your browser at http://localhost:3000 with a simple placeholder page:

    Screenshot of new Wasp app

    Wasp has generated for you the full front-end and back-end code the app! Next, we'll take a closer look at how the project is structured.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/tutorial/entities.html b/docs/0.12.0/tutorial/entities.html index c6a9ac02b3..ca58f3d271 100644 --- a/docs/0.12.0/tutorial/entities.html +++ b/docs/0.12.0/tutorial/entities.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.12.0

    4. Database Entities

    Entities are one of the most important concepts in Wasp and are how you define what gets stored in the database.

    Since our Todo app is all about tasks, we will define a Task entity in the Wasp file:

    main.wasp
    // ...

    entity Task {=psl
        id          Int     @id @default(autoincrement())
        description String
        isDone      Boolean @default(false)
    psl=}
    note

    Wasp uses Prisma as a way to talk to the database. You define entities by defining Prisma models using the Prisma Schema Language (PSL) between the {=psl psl=} tags.

    Read more in the Entities section of the docs.

    To update the database schema to include this entity, stop the wasp start process, if it's running, and run:

    wasp db migrate-dev

    You'll need to do this any time you change an entity's definition. It instructs Prisma to create a new database migration and apply it to the database.

    To take a look at the database and the new Task entity, run:

    wasp db studio

    This will open a new page in your browser to view and edit the data in your database.

    Todo App - Db studio showing Task schema

    Click on the Task entity and check out its fields! We don't have any data in our database yet, but we are about to change that.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/tutorial/pages.html b/docs/0.12.0/tutorial/pages.html index 42440ee383..ac518a86ef 100644 --- a/docs/0.12.0/tutorial/pages.html +++ b/docs/0.12.0/tutorial/pages.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.12.0

    3. Pages & Routes

    In the default main.wasp file created by wasp new, there is a page and a route declaration:

    main.wasp
    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      // We specify that the React implementation of the page is exported from 
      // `src/MainPage.jsx`. This statement uses standard JS import syntax.
      // Use `@src` to reference files inside the `src` folder.
      component: import { MainPage } from "@src/MainPage"
    }

    Together, these declarations tell Wasp that when a user navigates to /, it should render the named export from src/MainPage.tsx.

    The MainPage Component​

    Let's take a look at the React component referenced by the page declaration:

    src/MainPage.jsx
    import waspLogo from './waspLogo.png'
    import './Main.css'

    export const MainPage = () => {
      // ...
    }

    This is a regular functional React component. It also uses the CSS file and a logo image that sit next to it in the src folder.

    That is all the code you need! Wasp takes care of everything else necessary to define, build, and run the web app.

    tip

    wasp start automatically picks up the changes you make and restarts the app, so keep it running in the background.

    Adding a Second Page​

    To add more pages, you can create another set of page and route declarations. You can even add parameters to the URL path, using the same syntax as React Router. Let's test this out by adding a new page:

    main.wasp
    route HelloRoute { path: "/hello/:name", to: HelloPage }
    page HelloPage {
      component: import { HelloPage } from "@src/HelloPage"
    }

    When a user visits /hello/their-name, Wasp will render the component exported from src/HelloPage.tsx and pass the URL parameter the same way as in React Router:

    src/HelloPage.jsx
    export const HelloPage = (props) =>  {
      return <div>Here's {props.match.params.name}!</div>
    }

    Now you can visit /hello/johnny and see "Here's johnny!"

    Cleaning Up​

    Now that you've seen how Wasp deals with Routes and Pages, it's finally time to build the Todo app.

    Start by cleaning up the starter project and removing unnecessary code and files.

    First, remove most of the code from the MainPage component:

    src/MainPage.jsx
    export const MainPage = () => {
      return <div>Hello world!</div>
    }

    At this point, the main page should look like this:

    Todo App - Hello World

    You can now delete redundant files: src/Main.css, src/waspLogo.png, and src/HelloPage.tsx (we won't need this page for the rest of the tutorial).

    Since src/HelloPage.tsx no longer exists, remove its route and page declarations from the main.wasp file.

    Your Wasp file should now look like this:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.12.0"
      },
      title: "TodoApp"
    }

    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      component: import { MainPage } from "@src/MainPage"
    }

    Excellent work!

    You now have a basic understanding of Wasp and are ready to start building your TodoApp. We'll implement the app's core features in the following sections.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/tutorial/project-structure.html b/docs/0.12.0/tutorial/project-structure.html index 7afaabf74c..3a3e709ea0 100644 --- a/docs/0.12.0/tutorial/project-structure.html +++ b/docs/0.12.0/tutorial/project-structure.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ We'll keep it simple by placing everything in the root src directory.

    Many other files (e.g., tsconfig.json, vite-env.d.ts, .wasproot, etc.) help Wasp and the IDE improve your development experience with autocompletion, IntelliSense, and error reporting.

    The vite.config.ts file is used to configure Vite, Wasp's build tool of choice. We won't be configuring Vite in this tutorial, so you can safely ignore the file. Still, if you ever end up wanting more control over Vite, you'll find everything you need to know in custom Vite config docs.

    There's no need to spend more time discussing all the helper files. They'll silently do their job in the background and let you focus on building your app.

    TypeScript Support

    Wasp supports TypeScript out of the box, but you are free to choose between or mix JavaScript and TypeScript as you see fit.

    We'll provide you with both JavaScript and TypeScript code in this tutorial. Code blocks will have a toggle to switch between vanilla JavaScript and TypeScript.

    The most important file in the project is main.wasp. Wasp uses the configuration within it to perform its magic. Based on what you write, it generates a bunch of code for your database, server-client communication, React routing, and more.

    Let's take a closer look at main.wasp

    main.wasp​

    main.wasp is your app's definition file. It defines the app's central components and helps Wasp to do a lot of the legwork for you.

    The file is a list of declarations. Each declaration defines a part of your app.

    The default main.wasp file generated with wasp new on the previous page looks like this:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.12.0" // Pins the version of Wasp to use.
      },
      title: "TodoApp" // Used as the browser tab title. Note that all strings in Wasp are double quoted!
    }

    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      // We specify that the React implementation of the page is exported from
      // `src/MainPage.jsx`. This statement uses standard JS import syntax.
      // Use `@src` to reference files inside the `src` folder.
      component: import { MainPage } from "@src/MainPage"
    }

    This file uses three declaration types:

    • app: Top-level configuration information about your app.

    • route: Describes which path each page should be accessible from.

    • page: Defines a web page and the React component that gets rendered when the page is loaded.

    In the next section, we'll explore how route and page work together to build your web app.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/tutorial/queries.html b/docs/0.12.0/tutorial/queries.html index 77e4a37408..0c7f38c226 100644 --- a/docs/0.12.0/tutorial/queries.html +++ b/docs/0.12.0/tutorial/queries.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.12.0

    5. Querying the Database

    We want to know which tasks we need to do, so let's list them!

    The primary way of working with Entities in Wasp is with Queries and Actions, collectively known as Operations.

    Queries are used to read an entity, while Actions are used to create, modify, and delete entities. Since we want to list the tasks, we'll want to use a Query.

    To list the tasks, you must:

    1. Create a Query that fetches the tasks from the database.
    2. Update the MainPage.tsx to use that Query and display the results.

    Defining the Query​

    We'll create a new Query called getTasks. We'll need to declare the Query in the Wasp file and write its implementation in .

    Declaring a Query​

    We need to add a query declaration to main.wasp so that Wasp knows it exists:

    main.wasp
    // ...

    query getTasks {
      // Specifies where the implementation for the query function is.
      // The path `@src/queries` resolves to `src/queries.js`.
      // No need to specify an extension.
      fn: import { getTasks } from "@src/queries",
      // Tell Wasp that this query reads from the `Task` entity. Wasp will
      // automatically update the results of this query when tasks are modified.
      entities: [Task]
    }

    Implementing a Query​

    src/queries.js
    export const getTasks = async (args, context) => {
      return context.entities.Task.findMany({
        orderBy: { id: 'asc' },
      })
    }

    Query function parameters:

    • args: object

      The arguments the caller passes to the Query.

    • context

      An object with extra information injected by Wasp. Its type depends on the Query declaration.

    Since the Query declaration in main.wasp says that the getTasks Query uses Task entity, Wasp injected a Prisma client for the Task entity as context.entities.Task - we used it above to fetch all the tasks from the database.

    info

    Queries and Actions are NodeJS functions executed on the server.

    Invoking the Query On the Frontend​

    While we implement Queries on the server, Wasp generates client-side functions that automatically take care of serialization, network calls, and cache invalidation, allowing you to call the server code like it's a regular function.

    This makes it easy for us to use the getTasks Query we just created in our React component:

    src/MainPage.jsx
    import { getTasks, useQuery } from 'wasp/client/operations'

    export const MainPage = () => {
      const { data: tasks, isLoading, error } = useQuery(getTasks)

      return (
        <div>
          {tasks && <TasksList tasks={tasks} />}

          {isLoading && 'Loading...'}
          {error && 'Error: ' + error}
        </div>
      )
    }

    const TaskView = ({ task }) => {
      return (
        <div>
          <input type="checkbox" id={String(task.id)} checked={task.isDone} />
          {task.description}
        </div>
      )
    }

    const TasksList = ({ tasks }) => {
      if (!tasks?.length) return <div>No tasks</div>

      return (
        <div>
          {tasks.map((task, idx) => (
            <TaskView task={task} key={idx} />
          ))}
        </div>
      )
    }

    Most of this code is regular React, the only exception being the special wasp imports:

    We could have called the Query directly using getTasks(), but the useQuery hook makes it reactive: React will re-render the component every time the Query changes. Remember that Wasp automatically refreshes Queries whenever the data is modified.

    With these changes, you should be seeing the text "No tasks" on the screen:

    Todo App - No Tasks

    We'll create a form to add tasks in the next step 🪄

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/vision.html b/docs/0.12.0/vision.html index 7e1da4fcb7..596c21fd08 100644 --- a/docs/0.12.0/vision.html +++ b/docs/0.12.0/vision.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -33,7 +33,7 @@ They can be used inline (mixed with Wasp code) or provided via external files.
  • Has hatches (escape mechanisms) that allow you to customize your web app in all the right places, but remain hidden until you need them.
  • Entity (data model) is a first-class citizen - defined via custom Wasp syntax and it integrates very closely with the rest of the features, serving as one of the central concepts around which everything is built.
  • Out of the box support for CRUD UI based on the Entities, to get you quickly going, but also customizable to some level.
  • "Smart" operations (queries and actions) that in most cases automatically figure out when to update, and if not it is easy to define custom logic to compensate for that. User worries about client-server gap as little as possible.
  • Support, directly in Wasp, for declaratively defining simple components and operations.
  • Besides Wasp as a programming language, there will also be a visual builder that generates/edits Wasp code, allowing non-developers to participate in development. Since Wasp is declarative, we imagine such builder to naturally follow from Wasp language.
  • Server side rendering, caching, packaging, security, ... -> all those are taken care of by Wasp. You tell Wasp what you want, and Wasp figures out how to do it.
  • As simple deployment to production/staging as it gets.
  • While it comes with the official implementation(s), Wasp language will not be coupled with the single implementation. Others can provide implementations that compile to different web app stacks.
    • - - + + \ No newline at end of file diff --git a/docs/0.12.0/wasp-ai/creating-new-app.html b/docs/0.12.0/wasp-ai/creating-new-app.html index cdf64c4810..8c3664d059 100644 --- a/docs/0.12.0/wasp-ai/creating-new-app.html +++ b/docs/0.12.0/wasp-ai/creating-new-app.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.12.0

    Creating New App with AI

    Wasp comes with its own AI: Wasp AI, aka Mage (Magic web App GEnerator).

    Wasp AI allows you to create a new Wasp app from only a title and a short description (using GPT in the background)!

    There are two main ways to create a new Wasp app with Wasp AI:

    1. Free, open-source online app usemage.ai.
    2. Running wasp new on your machine and picking AI generation. For this you need to provide your own OpenAI API keys, but it allows for more flexibility (choosing GPT models).

    They both use the same logic in the background, so both approaches are equally "smart", the difference is just in the UI / settings.

    info

    Wasp AI is an experimental feature. Apps that Wasp AI generates can have mistakes (proportional to their complexity), but even then they can often serve as a great starting point (once you fix the mistakes) or an interesting way to explore how to implement stuff in Wasp.

    usemage.ai​

    1. Describe your app 2. Pick the color 3. Generate your app 🚀

    Mage is an open-source app with which you can create new Wasp apps from just a short title and description.

    It is completely free for you - it uses our OpenAI API keys and we take on the costs.

    Once you provide an app title, app description, and choose some basic settings, your new Wasp app will be created for you in a matter of minutes and you will be able to download it to your machine and keep working on it!

    If you want to know more, check this blog post for more details on how Mage works, or this blog post for a high-level overview of how we implemented it.

    Wasp Cli​

    You can create a new Wasp app using Wasp AI by running wasp new in your terminal and picking AI generation.

    If you don't have them set yet, wasp will ask you to provide (via ENV vars) your OpenAI API keys (which it will use to query GPT).

    Then, after providing a title and description for your Wasp app, the new app will be generated on your disk!

    wasp-cli-ai-input wasp-cli-ai-generation

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/wasp-ai/developing-existing-app.html b/docs/0.12.0/wasp-ai/developing-existing-app.html index 9a7e09e44b..0a00c4eba7 100644 --- a/docs/0.12.0/wasp-ai/developing-existing-app.html +++ b/docs/0.12.0/wasp-ai/developing-existing-app.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.12.0

    Developing Existing App with AI

    While Wasp AI doesn't at the moment offer any additional help for developing your Wasp app with AI beyond initial generation, this is something we are exploring actively.

    In the meantime, while waiting for Wasp AI to add support for this, we suggest checking out aider, which is an AI pair programming tool in your terminal. This is a third-party tool, not affiliated with Wasp in any way, but we and some of Wasp users have found that it can be helpful when working on Wasp apps.

    - - + + \ No newline at end of file diff --git a/docs/0.12.0/writingguide.html b/docs/0.12.0/writingguide.html index e901f6164b..8103437298 100644 --- a/docs/0.12.0/writingguide.html +++ b/docs/0.12.0/writingguide.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -53,7 +53,7 @@ Many of our titles are currently in title-case, we should start phasing those out.
  • Use the Oxford comma (e.g., "a, b, and c" instead of "a, b and c"). Why the Oxford comma is important

    • 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/0.13.0.html b/docs/0.13.0.html index aa81901e7b..1410b2df1c 100644 --- a/docs/0.13.0.html +++ b/docs/0.13.0.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -30,7 +30,7 @@ which are in their essence a Node.js functions that execute on server and can, thanks to Wasp, very easily be called from the client.

    First, we define these Operations in our main.wasp file, so Wasp knows about them and can "beef them up":

    main.wasp
    // Queries have automatic cache invalidation and are type-safe.
    query getRecipes {
      fn: import { getRecipes } from "@src/recipe/operations.ts",
      entities: [Recipe],
    }

    // Actions are type-safe and can be used to perform side-effects.
    action addRecipe {
      fn: import { addRecipe } from "@src/recipe/operations.ts",
      entities: [Recipe],
    }

    ... and then implement them in our Javascript (or TypeScript) code (we show just the query here, using TypeScript):

    src/recipe/operations.ts
    // Wasp generates the types for you.
    import { type GetRecipes } from "wasp/server/operations";
    import { type Recipe } from "wasp/entities";

    export const getRecipes: GetRecipes<{}, Recipe[]> = async (_args, context) => {
      return context.entities.Recipe.findMany( // Prisma query
        { where: { user: { id: context.user.id } } }
      );
    };

    export const addRecipe ...

    Now we can very easily use these in our React components!

    For the end, let's create a home page of our app.

    First we define it in main.wasp:

    main.wasp
    ...

    route HomeRoute { path: "/", to: HomePage }
    page HomePage {
      component: import { HomePage } from "@src/pages/HomePage",
      authRequired: true // Will send user to /login if not authenticated.
    }

    and then implement it as a React component in JS/TS (that calls the Operations we previously defined):

    src/pages/HomePage.tsx
    import { useQuery, getRecipes } from "wasp/client/operations";
    import { type User } from "wasp/entities";

    export function HomePage({ user }: { user: User }) {
      // Due to full-stack type safety, `recipes` will be of type `Recipe[]` here.
      const { data: recipes, isLoading } = useQuery(getRecipes); // Calling our query here!

      if (isLoading) {
        return <div>Loading...</div>;
      }

      return (
        <div>
          <h1>Recipes</h1>
          <ul>
            {recipes ? recipes.map((recipe) => (
              <li key={recipe.id}>
                <div>{recipe.title}</div>
                <div>{recipe.description}</div>
              </li>
            )) : 'No recipes defined yet!'}
          </ul>
        </div>
      );
    }

    And voila! We are listing all the recipes in our app 🎉

    This was just a quick example to give you a taste of what Wasp is. For step by step tour through the most important Wasp features, check out the Todo app tutorial.

    note

    Above we skipped defining /login and /signup pages to keep the example a bit shorter, but those are very simple to do by using Wasp's Auth UI feature.

    When to use Wasp​

    Wasp is addressing the same core problems that typical web app frameworks are addressing, and it in big part looks, swims and quacks like a web app framework.

    Best used for​

    • building full-stack web apps (like e.g. Airbnb or Asana)
    • quickly starting a web app with industry best practices
    • to be used alongside modern web dev stack (currently supported React and Node)

    Avoid using Wasp for​

    • building static/presentational websites
    • to be used as a no-code solution
    • to be a solve-it-all tool in a single language

    Wasp is a DSL​

    note

    You don't need to know what a DSL is to use Wasp, but if you are curious, you can read more about it below.

    Wasp does not match typical expectations of a web app framework: it is not a set of libraries, it is instead a simple programming language that understands your code and can do a lot of things for you.

    Wasp is a programming language, but a specific kind: it is specialized for a single purpose: building modern web applications. We call such languages DSLs (Domain Specific Language).

    Other examples of DSLs that are often used today are e.g. SQL for databases and HTML for web page layouts. The main advantage and reason why DSLs exist is that they need to do only one task (e.g. database queries) so they can do it well and provide the best possible experience for the developer.

    The same idea stands behind Wasp - a language that will allow developers to build modern web applications with 10x less code and less stack-specific knowledge.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/advanced/accessing-app-config.html b/docs/0.13.0/advanced/accessing-app-config.html index d882978446..dc1a6d9178 100644 --- a/docs/0.13.0/advanced/accessing-app-config.html +++ b/docs/0.13.0/advanced/accessing-app-config.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -37,7 +37,7 @@ Wasp automatically sets it during development when you run wasp start.
    In production, it should contain the value of your server's URL as the user's browser sees it (i.e., with the DNS and proxies considered).

    You can access it like this:

    import { config } from 'wasp/client'

    console.log(config.apiUrl)
    - - + + \ No newline at end of file diff --git a/docs/0.13.0/advanced/apis.html b/docs/0.13.0/advanced/apis.html index 6d2f8c1c9d..e5a17dbf91 100644 --- a/docs/0.13.0/advanced/apis.html +++ b/docs/0.13.0/advanced/apis.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.13.0

    Custom HTTP API Endpoints

    In Wasp, the default client-server interaction mechanism is through Operations. However, if you need a specific URL method/path, or a specific response, Operations may not be suitable for you. For these cases, you can use an api. Best of all, they should look and feel very familiar.

    How to Create an API​

    APIs are used to tie a JS function to a certain endpoint e.g. POST /something/special. They are distinct from Operations and have no client-side helpers (like useQuery).

    To create a Wasp API, you must:

    1. Declare the API in Wasp using the api declaration
    2. Define the API's NodeJS implementation

    After completing these two steps, you'll be able to call the API from the client code (via our Axios wrapper), or from the outside world.

    Declaring the API in Wasp​

    First, we need to declare the API in the Wasp file and you can easily do this with the api declaration:

    main.wasp
    // ...

    api fooBar { // APIs and their implementations don't need to (but can) have the same name.
      fn: import { fooBar } from "@src/apis",
      httpRoute: (GET, "/foo/bar")
    }

    Read more about the supported fields in the API Reference.

    Defining the API's NodeJS Implementation​

    After you defined the API, it should be implemented as a NodeJS function that takes three arguments:

    1. req: Express Request object
    2. res: Express Response object
    3. context: An additional context object injected into the API by Wasp. This object contains user session information, as well as information about entities. The examples here won't use the context for simplicity purposes. You can read more about it in the section about using entities in APIs.
    src/apis.js
    export const fooBar = (req, res, context) => {
      res.set("Access-Control-Allow-Origin", "*"); // Example of modifying headers to override Wasp default CORS middleware.
      res.json({ msg: `Hello, ${context.user ? "registered user" : "stranger"}!` });
    };

    Using the API​

    Using the API externally​

    To use the API externally, you simply call the endpoint using the method and path you used.

    For example, if your app is running at https://example.com then from the above you could issue a GET to https://example/com/foo/callback (in your browser, Postman, curl, another web service, etc.).

    Using the API from the Client​

    To use the API from your client, including with auth support, you can import the Axios wrapper from wasp/client/api and invoke a call. For example:

    src/pages/SomePage.jsx
    import React, { useEffect } from "react";
    import { api } from "wasp/client/api";

    async function fetchCustomRoute() {
      const res = await api.get("/foo/bar");
      console.log(res.data);
    }

    export const Foo = () => {
      useEffect(() => {
        fetchCustomRoute();
      }, []);

      return <>// ...</>;
    };

    Making Sure CORS Works​

    APIs are designed to be as flexible as possible, hence they don't utilize the default middleware like Operations do. As a result, to use these APIs on the client side, you must ensure that CORS (Cross-Origin Resource Sharing) is enabled.

    You can do this by defining custom middleware for your APIs in the Wasp file.

    For example, an apiNamespace is a simple declaration used to apply some middlewareConfigFn to all APIs under some specific path:

    main.wasp
    apiNamespace fooBar {
      middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@src/apis",
      path: "/foo"
    }

    And then in the implementation file:

    src/apis.js
    export const apiMiddleware = (config) => {
      return config;
    };

    We are returning the default middleware which enables CORS for all APIs under the /foo path.

    For more information about middleware configuration, please see: Middleware Configuration

    Using Entities in APIs​

    In many cases, resources used in APIs will be Entities. To use an Entity in your API, add it to the api declaration in Wasp:

    main.wasp
    api fooBar {
      fn: import { fooBar } from "@src/apis",
      entities: [Task],
      httpRoute: (GET, "/foo/bar")
    }

    Wasp will inject the specified Entity into the APIs context argument, giving you access to the Entity's Prisma API:

    src/apis.js
    export const fooBar = (req, res, context) => {
      res.json({ count: await context.entities.Task.count() });
    };

    The object context.entities.Task exposes prisma.task from Prisma's CRUD API.

    API Reference​

    main.wasp
    api fooBar {
      fn: import { fooBar } from "@src/apis",
      httpRoute: (GET, "/foo/bar"),
      entities: [Task],
      auth: true,
      middlewareConfigFn: import { apiMiddleware } from "@src/apis"
    }

    The api declaration has the following fields:

    • fn: ExtImport required

      The import statement of the APIs NodeJs implementation.

    • httpRoute: (HttpMethod, string) required

      The HTTP (method, path) pair, where the method can be one of:

      • ALL, GET, POST, PUT or DELETE
      • and path is an Express path string.

    • entities: [Entity]

      A list of entities you wish to use inside your API. You can read more about it here.

    • auth: bool

      If auth is enabled, this will default to true and provide a context.user object. If you do not wish to attempt to parse the JWT in the Authorization Header, you should set this to false.

    • middlewareConfigFn: ExtImport

      The import statement to an Express middleware config function for this API. See more in middleware section of the docs.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/advanced/deployment/cli.html b/docs/0.13.0/advanced/deployment/cli.html index 28c506a479..189f2b813c 100644 --- a/docs/0.13.0/advanced/deployment/cli.html +++ b/docs/0.13.0/advanced/deployment/cli.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.13.0

    Deploying with the Wasp CLI

    Wasp CLI can deploy your full-stack application with only a single command. The command automates the manual deployment process and is the recommended way of deploying Wasp apps.

    Supported Providers​

    Wasp supports automated deployment to the following providers:

    • Fly.io - they offer 5$ free credit each month
    • Railway (coming soon, track it here #1157)

    Fly.io​

    Prerequisites​

    Fly provides free allowances for up to 3 VMs (so deploying a Wasp app to a new account is free), but all plans require you to add your credit card information before you can proceed. If you don't, the deployment will fail.

    You can add the required credit card information on the account's billing page.

    Fly.io CLI

    You will need the flyctl CLI installed on your machine before you can deploy to Fly.io.

    Deploying​

    Using the Wasp CLI, you can easily deploy a new app to Fly.io with just a single command:

    wasp deploy fly launch my-wasp-app mia
    Specifying Org

    If your account is a member of more than one organization on Fly.io, you will need to specify under which one you want to execute the command. To do that, provide an additional --org <org-slug> option. You can find out the names(slugs) of your organizations by running fly orgs list.

    Please do not CTRL-C or exit your terminal while the commands are running.

    Under the covers, this runs the equivalent of the following commands:

    wasp deploy fly setup my-wasp-app mia
    wasp deploy fly create-db mia
    wasp deploy fly deploy

    The commands above use the app basename my-wasp-app and deploy it to the Miami, Florida (US) region (called mia). Read more about Fly.io regions here.

    Unique Name

    Your app name must be unique across all of Fly or deployment will fail.

    The basename is used to create all three app tiers, resulting in three separate apps in your Fly dashboard:

    • my-wasp-app-client
    • my-wasp-app-server
    • my-wasp-app-db

    You'll notice that Wasp creates two new files in your project root directory:

    • fly-server.toml
    • fly-client.toml

    You should include these files in your version control so that you can deploy your app with a single command in the future.

    Using a Custom Domain For Your App​

    Setting up a custom domain is a three-step process:

    1. You need to add your domain to your Fly client app. You can do this by running:
    wasp deploy fly cmd --context client certs create mycoolapp.com
    Use Your Domain

    Make sure to replace mycoolapp.com with your domain in all of the commands mentioned in this section.

    This command will output the instructions to add the DNS records to your domain. It will look something like this:

    You can direct traffic to mycoolapp.com by:

    1: Adding an A record to your DNS service which reads

        A @ 66.241.1XX.154

    You can validate your ownership of mycoolapp.com by:

    2: Adding an AAAA record to your DNS service which reads:

        AAAA @ 2a09:82XX:1::1:ff40

    1. You need to add the DNS records for your domain:

      This will depend on your domain provider, but it should be a matter of adding an A record for @ and an AAAA record for @ with the values provided by the previous command.

    2. You need to set your domain as the WASP_WEB_CLIENT_URL environment variable for your server app:

    wasp deploy fly cmd --context server secrets set WASP_WEB_CLIENT_URL=https://mycoolapp.com

    We need to do this to keep our CORS configuration up to date.

    That's it, your app should be available at https://mycoolapp.com! 🎉

    API Reference​

    launch​

    launch is a convenience command that runs setup, create-db, and deploy in sequence.

    wasp deploy fly launch <app-name> <region>

    It accepts the following arguments:

    • <app-name> - the name of your app required

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    It gives you the same result as running the following commands:

    wasp deploy fly setup <app-name> <region>
    wasp deploy fly create-db <region>
    wasp deploy fly deploy

    Environment Variables​

    If you are deploying an app that requires any other environment variables (like social auth secrets), you can set them with the --server-secret option:

    wasp deploy fly launch my-wasp-app mia --server-secret GOOGLE_CLIENT_ID=<...> --server-secret GOOGLE_CLIENT_SECRET=<...>

    setup​

    setup will create your client and server apps on Fly, and add some secrets, but does not deploy them.

    wasp deploy fly setup <app-name> <region>

    It accepts the following arguments:

    • <app-name> - the name of your app required

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    After running setup, Wasp creates two new files in your project root directory: fly-server.toml and fly-client.toml. You should include these files in your version control.

    You can edit the fly-server.toml and fly-client.toml files to further configure your Fly deployments. Wasp will use the TOML files when you run deploy.

    If you want to maintain multiple apps, you can add the --fly-toml-dir <abs-path> option to point to different directories, like "dev" or "staging".

    Execute Only Once

    You should only run setup once per app. If you run it multiple times, it will create unnecessary apps on Fly.

    create-db​

    create-db will create a new database for your app.

    wasp deploy fly create-db <region>

    It accepts the following arguments:

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    Execute Only Once

    You should only run create-db once per app. If you run it multiple times, it will create multiple databases, but your app needs only one.

    deploy​

    wasp deploy fly deploy

    deploy pushes your client and server live.

    Run this command whenever you want to update your deployed app with the latest changes:

    wasp deploy fly deploy

    cmd​

    If want to run arbitrary Fly commands (e.g. flyctl secrets list for your server app), here's how to do it:

    wasp deploy fly cmd secrets list --context server

    Fly.io Regions​

    Fly.io runs applications physically close to users: in datacenters around the world, on servers we run ourselves. You can currently deploy your apps in 34 regions, connected to a global Anycast network that makes sure your users hit our nearest server, whether they’re in Tokyo, São Paolo, or Frankfurt.

    Read more on Fly regions here.

    You can find the list of all available Fly regions by running:

    flyctl platform regions

    Environment Variables​

    If you are deploying an app that requires any other environment variables (like social auth secrets), you can set them with the secrets set command:

    wasp deploy fly cmd secrets set GOOGLE_CLIENT_ID=<...> GOOGLE_CLIENT_SECRET=<...> --context=server

    Multiple Fly Organizations​

    If you have multiple organizations, you can specify a --org option. For example:

    wasp deploy fly launch my-wasp-app mia --org hive

    Building Locally​

    Fly.io offers support for both locally built Docker containers and remotely built ones. However, for simplicity and reproducibility, the CLI defaults to the use of a remote Fly.io builder.

    If you want to build locally, supply the --build-locally option to wasp deploy fly launch or wasp deploy fly deploy.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/advanced/deployment/manually.html b/docs/0.13.0/advanced/deployment/manually.html index 6a73a75d6e..b30e201599 100644 --- a/docs/0.13.0/advanced/deployment/manually.html +++ b/docs/0.13.0/advanced/deployment/manually.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -40,7 +40,7 @@ Set it to a random string at least 32 characters long (you can use an online generator).

  • PORT

    The server's HTTP port number. This is where the server listens for requests (default: 3001).

    • 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/0.13.0/advanced/deployment/overview.html b/docs/0.13.0/advanced/deployment/overview.html index 903faa6a80..68e7488590 100644 --- a/docs/0.13.0/advanced/deployment/overview.html +++ b/docs/0.13.0/advanced/deployment/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ 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.13.0/advanced/email.html b/docs/0.13.0/advanced/email.html index ac51cfd5d3..9fe39dda93 100644 --- a/docs/0.13.0/advanced/email.html +++ b/docs/0.13.0/advanced/email.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/advanced/jobs.html b/docs/0.13.0/advanced/jobs.html index 01643b2cc1..61aa57e70d 100644 --- a/docs/0.13.0/advanced/jobs.html +++ b/docs/0.13.0/advanced/jobs.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/advanced/links.html b/docs/0.13.0/advanced/links.html index fa0b6fed6b..c7f8607b41 100644 --- a/docs/0.13.0/advanced/links.html +++ b/docs/0.13.0/advanced/links.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/advanced/middleware-config.html b/docs/0.13.0/advanced/middleware-config.html index 2805563e30..c0ea694dff 100644 --- a/docs/0.13.0/advanced/middleware-config.html +++ b/docs/0.13.0/advanced/middleware-config.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/advanced/web-sockets.html b/docs/0.13.0/advanced/web-sockets.html index 859b869822..42c4d288c2 100644 --- a/docs/0.13.0/advanced/web-sockets.html +++ b/docs/0.13.0/advanced/web-sockets.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/auth/email.html b/docs/0.13.0/auth/email.html index 9b743898cd..8c3f76315c 100644 --- a/docs/0.13.0/auth/email.html +++ b/docs/0.13.0/auth/email.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/auth/entities.html b/docs/0.13.0/auth/entities.html index b6a4a1d52a..935e8c4956 100644 --- a/docs/0.13.0/auth/entities.html +++ b/docs/0.13.0/auth/entities.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/auth/overview.html b/docs/0.13.0/auth/overview.html index b9b54f6c20..c45cc3caa1 100644 --- a/docs/0.13.0/auth/overview.html +++ b/docs/0.13.0/auth/overview.html @@ -18,16 +18,16 @@ - - - + + +
    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

    Discord »

    Users sign in with their Discord 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",
      }
    }

    //...

    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

    Discord »

    Users sign in with their Discord 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 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.13.0/auth/social-auth/github.html b/docs/0.13.0/auth/social-auth/github.html index e70edcf197..03515a16a0 100644 --- a/docs/0.13.0/auth/social-auth/github.html +++ b/docs/0.13.0/auth/social-auth/github.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ 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/0.13.0/auth/social-auth/google.html b/docs/0.13.0/auth/social-auth/google.html index fc519f4aad..5066d77a32 100644 --- a/docs/0.13.0/auth/social-auth/google.html +++ b/docs/0.13.0/auth/social-auth/google.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ 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/0.13.0/auth/social-auth/keycloak.html b/docs/0.13.0/auth/social-auth/keycloak.html index 1d04fd6073..03d62905d4 100644 --- a/docs/0.13.0/auth/social-auth/keycloak.html +++ b/docs/0.13.0/auth/social-auth/keycloak.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ 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/0.13.0/auth/social-auth/overview.html b/docs/0.13.0/auth/social-auth/overview.html index 3fd0484fd8..c803e097eb 100644 --- a/docs/0.13.0/auth/social-auth/overview.html +++ b/docs/0.13.0/auth/social-auth/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -31,7 +31,7 @@ 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.13.0/auth/ui.html b/docs/0.13.0/auth/ui.html index 3666a989b0..d640130108 100644 --- a/docs/0.13.0/auth/ui.html +++ b/docs/0.13.0/auth/ui.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/auth/username-and-pass.html b/docs/0.13.0/auth/username-and-pass.html index 032a625fee..6ba131bed9 100644 --- a/docs/0.13.0/auth/username-and-pass.html +++ b/docs/0.13.0/auth/username-and-pass.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/contact.html b/docs/0.13.0/contact.html index 88fd632b83..71665cc9dd 100644 --- a/docs/0.13.0/contact.html +++ b/docs/0.13.0/contact.html @@ -18,14 +18,14 @@ - - - + + +
    - - + + \ No newline at end of file diff --git a/docs/0.13.0/contributing.html b/docs/0.13.0/contributing.html index b0bb8a921b..52cc48f973 100644 --- a/docs/0.13.0/contributing.html +++ b/docs/0.13.0/contributing.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/data-model/backends.html b/docs/0.13.0/data-model/backends.html index 22f1257eea..9df28a2fad 100644 --- a/docs/0.13.0/data-model/backends.html +++ b/docs/0.13.0/data-model/backends.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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.13.0/data-model/crud.html b/docs/0.13.0/data-model/crud.html index 5a3fc0ab7a..d293ca30fc 100644 --- a/docs/0.13.0/data-model/crud.html +++ b/docs/0.13.0/data-model/crud.html @@ -18,16 +18,16 @@ - - - + + +
    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/0.13.0/data-model/entities.html b/docs/0.13.0/data-model/entities.html index dcf5fbc563..d8eeb170cc 100644 --- a/docs/0.13.0/data-model/entities.html +++ b/docs/0.13.0/data-model/entities.html @@ -18,16 +18,16 @@ - - - + + +
    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/0.13.0/data-model/operations/actions.html b/docs/0.13.0/data-model/operations/actions.html index f3b62d1257..df92244d95 100644 --- a/docs/0.13.0/data-model/operations/actions.html +++ b/docs/0.13.0/data-model/operations/actions.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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.13.0/data-model/operations/overview.html b/docs/0.13.0/data-model/operations/overview.html index b5c8f5cd16..1b34cc00db 100644 --- a/docs/0.13.0/data-model/operations/overview.html +++ b/docs/0.13.0/data-model/operations/overview.html @@ -18,15 +18,15 @@ - - - + + +
    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, Queries are meant for reading data, and Actions are meant for changing it (either by updating existing entries or creating new ones).

    Keep reading to find out all there is to know about Operations in Wasp.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/data-model/operations/queries.html b/docs/0.13.0/data-model/operations/queries.html index 71bdc28015..3f542c2f39 100644 --- a/docs/0.13.0/data-model/operations/queries.html +++ b/docs/0.13.0/data-model/operations/queries.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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.13.0/editor-setup.html b/docs/0.13.0/editor-setup.html index 643e9281ec..eef6c32107 100644 --- a/docs/0.13.0/editor-setup.html +++ b/docs/0.13.0/editor-setup.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/general/cli.html b/docs/0.13.0/general/cli.html index 9d93963b64..652ec60181 100644 --- a/docs/0.13.0/general/cli.html +++ b/docs/0.13.0/general/cli.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/general/language.html b/docs/0.13.0/general/language.html index 23b4aa1cb3..258ad1b83b 100644 --- a/docs/0.13.0/general/language.html +++ b/docs/0.13.0/general/language.html @@ -18,16 +18,16 @@ - - - + + +
    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/0.13.0/migrate-from-0-11-to-0-12.html b/docs/0.13.0/migrate-from-0-11-to-0-12.html index 3a3bf1f6de..940d037509 100644 --- a/docs/0.13.0/migrate-from-0-11-to-0-12.html +++ b/docs/0.13.0/migrate-from-0-11-to-0-12.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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.13.0/migrate-from-0-12-to-0-13.html b/docs/0.13.0/migrate-from-0-12-to-0-13.html index 81d26125d0..ffd1889251 100644 --- a/docs/0.13.0/migrate-from-0-12-to-0-13.html +++ b/docs/0.13.0/migrate-from-0-12-to-0-13.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/project/client-config.html b/docs/0.13.0/project/client-config.html index 13463cf81e..4edd82f4ac 100644 --- a/docs/0.13.0/project/client-config.html +++ b/docs/0.13.0/project/client-config.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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.13.0/project/css-frameworks.html b/docs/0.13.0/project/css-frameworks.html index a13aea4f1f..167da7c390 100644 --- a/docs/0.13.0/project/css-frameworks.html +++ b/docs/0.13.0/project/css-frameworks.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/project/custom-vite-config.html b/docs/0.13.0/project/custom-vite-config.html index fc1178425b..3e646e7356 100644 --- a/docs/0.13.0/project/custom-vite-config.html +++ b/docs/0.13.0/project/custom-vite-config.html @@ -18,14 +18,14 @@ - - - + + +
    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/0.13.0/project/customizing-app.html b/docs/0.13.0/project/customizing-app.html index af608109f2..1f94256dc8 100644 --- a/docs/0.13.0/project/customizing-app.html +++ b/docs/0.13.0/project/customizing-app.html @@ -18,15 +18,15 @@ - - - + + +
    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:

    • wasp: dict required Wasp compiler configuration. It is a dictionary with a single field:

      • version: string required

        The version specifies which versions of Wasp are compatible with the app. It should contain a valid SemVer range

        info

        For now, the version field only supports caret ranges (i.e., ^x.y.z). Support for the full specification will come in a future version of Wasp

    • title: string required

      Title of your app. It will appear in the browser tab, next to the favicon.

    • head: [string]

      List of additional lines (e.g. <link> or <script> tags) to be included in the <head> of your HTML document.

    The rest of the fields are covered in dedicated sections of the docs:

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/project/dependencies.html b/docs/0.13.0/project/dependencies.html index 451080c404..453815575b 100644 --- a/docs/0.13.0/project/dependencies.html +++ b/docs/0.13.0/project/dependencies.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.13.0

    Dependencies

    In a Wasp project, dependencies are defined in a standard way for JavaScript projects: using the package.json file, located at the root of your project. You can list your dependencies under the dependencies or devDependencies fields.

    Adding a New Dependency​

    To add a new package, like date-fns (a great date handling library), you use npm:

    npm install date-fns

    This command will add the package in the dependencies section of your package.json file.

    You will notice that there are some other packages in the dependencies section, like react and wasp. These are the packages that Wasp uses internally, and you should not modify or remove them.

    Using Packages that are Already Used by Wasp Internally​

    In the current version of Wasp, if Wasp is already internally using a certain dependency (e.g. React) with a certain version specified, you are not allowed to define that same npm dependency yourself while specifying a different version.

    If you do that, you will get an error message telling you which exact version you have to use for that dependency. This means Wasp dictates exact versions of certain packages, so for example you can't choose the version of React you want to use.

    note

    We are currently working on a restructuring that will solve this and some other quirks: check issue #734 to follow our progress.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/project/env-vars.html b/docs/0.13.0/project/env-vars.html index b841441946..bedaa3c93c 100644 --- a/docs/0.13.0/project/env-vars.html +++ b/docs/0.13.0/project/env-vars.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.13.0

    Env Variables

    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.

    For instance, during development, you may want your project to connect to a local development database running on your machine, but 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.

    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.

    In Wasp, you can use environment variables in both the client and the server code.

    Client Env Vars​

    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 never store secrets in them (such as secret API keys).

    To enable Wasp to pick them up, client environment variables must be prefixed with REACT_APP_, for example: REACT_APP_SOME_VAR_NAME=....

    You can read them from the client code like this:

    src/App.js
    console.log(import.meta.env.REACT_APP_SOME_VAR_NAME)

    Check below on how to define them.

    Server Env Vars​

    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 SOME_VAR_NAME=....

    You can read them in the server code like this:

    console.log(process.env.SOME_VAR_NAME)

    Check below on how to define them.

    Defining Env Vars in Development​

    During development, there are two ways to provide env vars to your Wasp project:

    1. Using .env files. (recommended)
    2. Using shell. (useful for overrides)

    1. Using .env (dotenv) Files​

    Env vars usage in development

    This is the recommended method for providing env vars to your Wasp project during development.

    In the root of your Wasp project you can create two distinct files:

    • .env.server for env vars that will be provided to the server.

      Variables are defined in these files in the form of NAME=VALUE, for example:

      .env.server
      DATABASE_URL=postgresql://localhost:5432
      SOME_VAR_NAME=somevalue

    • .env.client for env vars that will be provided to the client.

      Variables are defined in these files in the form of NAME=VALUE, for example:

      .env.client
      REACT_APP_SOME_VAR_NAME=somevalue

    These files should not be committed to version control, and they are already ignored by default in the .gitignore file that comes with Wasp.

    2. Using Shell​

    If you set environment variables in the shell where you run your Wasp commands (e.g., wasp start), Wasp will recognize them.

    You can set environment variables in the .profile or a similar file, or by defining them at the start of a command:

    SOME_VAR_NAME=SOMEVALUE wasp start

    This is not specific to Wasp and is simply how environment variables can be set in the shell.

    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 overriding specific environment variables because environment variables set this way take precedence over those defined in .env files.

    Defining Env Vars in Production​

    While in development, we had the option of using .env files which made it easy to define and manage env vars. However, in production, we need to provide env vars differently.

    Env vars usage in development and production

    Client Env Vars​

    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 never store secrets in them (such as secret API keys).

    You should provide them to the build command, for example:

    REACT_APP_SOME_VAR_NAME=somevalue npm run build
    How it works

    What happens behind the scenes is that Wasp will replace all occurrences of 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.

    Read more about it in Vite's docs.

    Server Env Vars​

    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 Fly, you can define them using the flyctl CLI tool:

    flyctl secrets set SOME_VAR_NAME=somevalue

    You can read a lot more details in the deployment section of the docs. We go into detail on how to define env vars for each deployment option.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/project/server-config.html b/docs/0.13.0/project/server-config.html index f9d8ae2bda..a4cc93f3f5 100644 --- a/docs/0.13.0/project/server-config.html +++ b/docs/0.13.0/project/server-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.13.0

    Server Config

    You can configure the behavior of the server via the server field of app declaration:

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      server: {
        setupFn: import { mySetupFunction } from "@src/myServerSetupCode.js",
        middlewareConfigFn: import { myMiddlewareConfigFn } from "@src/myServerSetupCode.js"
      }
    }

    Setup Function​

    Adding a Custom Route​

    As an example, adding a custom route would look something like:

    src/myServerSetupCode.ts
    export const mySetupFunction = async ({ app }) => {
      addCustomRoute(app)
    }

    function addCustomRoute(app) {
      app.get('/customRoute', (_req, res) => {
        res.send('I am a custom route')
      })
    }

    Storing Some Values for Later Use​

    In case you want to store some values for later use, or to be accessed by the Operations you do that in the setupFn function.

    Dummy example of such function and its usage:

    src/myServerSetupCode.js
    let someResource = undefined

    export const mySetupFunction = async () => {
      // Let's pretend functions setUpSomeResource and startSomeCronJob
      // are implemented below or imported from another file.
      someResource = await setUpSomeResource()
      startSomeCronJob()
    }

    export const getSomeResource = () => someResource
    src/queries.js
    import { getSomeResource } from './myServerSetupCode.js'

    ...

    export const someQuery = async (args, context) => {
      const someResource = getSomeResource()
      return queryDataFromSomeResource(args, someResource)
    }
    note

    The recommended way is to put the variable in the same module where you defined the setup function and then expose additional functions for reading those values, which you can then import directly from Operations and use.

    This effectively turns your module into a singleton whose construction is performed on server start.

    Read more about server setup function below.

    Middleware Config Function​

    You can configure the global middleware via the middlewareConfigFn. This will modify the middleware stack for all operations and APIs.

    Read more about middleware config function below.

    API Reference​

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      server: {
        setupFn: import { mySetupFunction } from "@src/myServerSetupCode.js",
        middlewareConfigFn: import { myMiddlewareConfigFn } from "@src/myServerSetupCode.js"
      }
    }

    app.server is a dictionary with the following fields:

    • setupFn: ExtImport​

      setupFn declares a function that will be executed on server start. This function is expected to be async and will be awaited before the server starts accepting any requests.

      It allows you to do any custom setup, e.g. setting up additional database/websockets or starting cron/scheduled jobs.

      The setupFn function receives the express.Application and the http.Server instances as part of its context. They can be useful for setting up any custom server logic.

      src/myServerSetupCode.js
      export const mySetupFunction = async () => {
        await setUpSomeResource()
      }

    • middlewareConfigFn: ExtImport​

      The import statement to an Express middleware config function. This is a global modification affecting all operations and APIs. See more in the configuring middleware section.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/project/starter-templates.html b/docs/0.13.0/project/starter-templates.html index b04e970fe3..08eaf55010 100644 --- a/docs/0.13.0/project/starter-templates.html +++ b/docs/0.13.0/project/starter-templates.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.13.0

    Starter Templates

    We created a few starter templates to help you get started with Wasp. Check out the list below.

    Using a Template​

    Run wasp new to run the interactive mode for creating a new Wasp project.

    It will ask you for the project name, and then for the template to use:

    $ 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

    Available Templates​

    When you have a good idea for a new product, you don't want to waste your time on setting up common things like authentication, database, etc. That's why we created a few starter templates to help you get started with Wasp.

    OpenSaaS.sh template​

    SaaS Template

    Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check out https://opensaas.sh/ for more details.

    Features: Stripe Payments, OpenAI GPT API, Google Auth, SendGrid, Tailwind, & Cron Jobs

    Use this template:

    wasp new <project-name> -t saas

    Vector Similarity Search Template​

    Vector Similarity Search Template

    A template for generating embeddings and performing vector similarity search on your text data!

    Features: Embeddings & vector similarity search, OpenAI Embeddings API, Vector DB (Pinecone), Tailwind, Full-stack Type Safety

    Use this template:

    wasp new <project-name> -t embeddings

    Todo App w/ Typescript​

    A simple Todo App with Typescript and Full-stack Type Safety.

    Features: Auth (username/password), Full-stack Type Safety

    Use this template:

    wasp new <project-name> -t todo-ts

    AI Generated Starter 🤖​

    Using the same tech as used on https://usemage.ai/, Wasp generates your custom starter template based on your project description. It will automatically generate your data model, auth, queries, actions and React pages.

    You will need to provide your own OpenAI API key to be able to use this template.

    Features: Generated using OpenAI's GPT models, Auth (username/password), Queries, Actions, Pages, Full-stack Type Safety

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/project/static-assets.html b/docs/0.13.0/project/static-assets.html index 26a872f8ea..937707502b 100644 --- a/docs/0.13.0/project/static-assets.html +++ b/docs/0.13.0/project/static-assets.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.13.0

    Static Asset Handling

    Importing an Asset as URL​

    Importing a static asset (e.g. an image) will return its URL. For example:

    src/App.jsx
    import imgUrl from './img.png'

    function App() {
      return <img src={imgUrl} alt="img" />
    }

    For example, imgUrl will be /img.png during development, and become /assets/img.2d8efhg.png in the production build.

    This is what you want to use most of the time, as it ensures that the asset file exists and is included in the bundle.

    We are using Vite under the hood, read more about importing static assets in Vite's docs.

    The public Directory​

    If you have assets that are:

    • Never referenced in source code (e.g. robots.txt)
    • Must retain the exact same file name (without hashing)
    • ...or you simply don't want to have to import an asset first just to get its URL

    Then you can place the asset in the public directory at the root of your project:

    .
    └── public
        ├── favicon.ico
        └── robots.txt

    Assets in this directory will be served at root path / during development and copied to the root of the dist directory as-is.

    For example, if you have a file favicon.ico in the public directory, and your app is hosted at https://myapp.com, it will be made available at https://myapp.com/favicon.ico.

    Usage in client code

    Note that:

    • You should always reference public assets using root absolute path
      • for example, public/icon.png should be referenced in source code as /icon.png.
    • Assets in the public directory cannot be imported from .
    - - + + \ No newline at end of file diff --git a/docs/0.13.0/project/testing.html b/docs/0.13.0/project/testing.html index 40b3a60e74..d550bf8559 100644 --- a/docs/0.13.0/project/testing.html +++ b/docs/0.13.0/project/testing.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.13.0

    Testing

    info

    Wasp is in beta, so keep in mind there might be some kinks / bugs, and possibly some changes with testing support in the future. If you encounter any issues, reach out to us on Discord and we will make sure to help you out!

    Testing Your React App​

    Wasp enables you to quickly and easily write both unit tests and React component tests for your frontend code. Because Wasp uses Vite, we support testing web apps through Vitest.

    Included Libraries

    vitest: Unit test framework with native Vite support.

    @vitest/ui: A nice UI for seeing your test results.

    jsdom: A web browser test environment for Node.js.

    @testing-library/react / @testing-library/jest-dom: Testing helpers.

    msw: A server mocking library.

    Writing Tests​

    For Wasp to pick up your tests, they should be placed within the src directory and use an extension that matches these glob patterns. Some of the file names that Wasp will pick up as tests:

    • yourFile.test.ts
    • YourComponent.spec.jsx

    Within test files, you can import your other source files as usual. For example, if you have a component Counter.jsx, you test it by creating a file in the same directory called Counter.test.jsx and import the component with import Counter from './Counter'.

    Running Tests​

    Running wasp test client will start Vitest in watch mode and recompile your Wasp project when changes are made.

    • If you want to see a real-time UI, pass --ui as an option.
    • To run the tests just once, use wasp test client run.

    All arguments after wasp test client are passed directly to the Vitest CLI, so check out their documentation for all of the options.

    Be Careful

    You should not run wasp test while wasp start is running. Both will try to compile your project to .wasp/out.

    React Testing Helpers​

    Wasp provides several functions to help you write React tests:

    • renderInContext: Takes a React component, wraps it inside a QueryClientProvider and Router, and renders it. This is the function you should use to render components in your React component tests.

      import { renderInContext } from "wasp/client/test";

      renderInContext(<MainPage />);

    • mockServer: Sets up the mock server and returns an object containing the mockQuery and mockApi utilities. This should be called outside of any test case, in each file that wants to use those helpers.

      import { mockServer } from "wasp/client/test";

      const { mockQuery, mockApi } = mockServer();

      • mockQuery: Takes a Wasp query to mock and the JSON data it should return.

        import { getTasks } from "wasp/client/operations";

        mockQuery(getTasks, []);
        • Helpful when your component uses useQuery.
        • Behind the scenes, Wasp uses msw to create a server request handle that responds with the specified data.
        • Mock are cleared between each test.

      • mockApi: Similar to mockQuery, but for APIs. Instead of a Wasp query, it takes a route containing an HTTP method and a path.

        import { HttpMethod } from "wasp/client";

        mockApi({ method: HttpMethod.Get, path: "/foor/bar" }, { res: "hello" });

    Testing Your Server-Side Code​

    Wasp currently does not provide a way to test your server-side code, but we will be adding support soon. You can track the progress at this GitHub issue and express your interest by commenting.

    Examples​

    You can see some tests in a Wasp project here.

    Client Unit Tests​

    src/helpers.js
    export function areThereAnyTasks(tasks) {
      return tasks.length === 0;
    }
    src/helpers.test.js
    import { test, expect } from "vitest";

    import { areThereAnyTasks } from "./helpers";

    test("areThereAnyTasks", () => {
      expect(areThereAnyTasks([])).toBe(false);
    });

    React Component Tests​

    src/Todo.jsx
    import { useQuery, getTasks } from "wasp/client/operations";

    const Todo = (_props) => {
      const { data: tasks } = useQuery(getTasks);
      return (
        <ul>
          {tasks &&
            tasks.map((task) => (
              <li key={task.id}>
                <input type="checkbox" value={task.isDone} />
                {task.description}
              </li>
            ))}
        </ul>
      );
    };
    src/Todo.test.jsx
    import { test, expect } from "vitest";
    import { screen } from "@testing-library/react";

    import { mockServer, renderInContext } from "wasp/client/test";
    import { getTasks } from "wasp/client/operations";
    import Todo from "./Todo";

    const { mockQuery } = mockServer();

    const mockTasks = [
      {
        id: 1,
        description: "test todo 1",
        isDone: true,
        userId: 1,
      },
    ];

    test("handles mock data", async () => {
      mockQuery(getTasks, mockTasks);

      renderInContext(<Todo />);

      await screen.findByText("test todo 1");

      expect(screen.getByRole("checkbox")).toBeChecked();

      screen.debug();
    });

    Testing With Mocked APIs​

    src/Todo.jsx
    import { api } from "wasp/client/api";

    const Todo = (_props) => {
      const [tasks, setTasks] = useState([]);
      useEffect(() => {
        api
          .get("/tasks")
          .then((res) => res.json())
          .then((tasks) => setTasks(tasks))
          .catch((err) => window.alert(err));
      });

      return (
        <ul>
          {tasks &&
            tasks.map((task) => (
              <li key={task.id}>
                <input type="checkbox" value={task.isDone} />
                {task.description}
              </li>
            ))}
        </ul>
      );
    };
    src/Todo.test.jsx
    import { test, expect } from "vitest";
    import { screen } from "@testing-library/react";

    import { mockServer, renderInContext } from "wasp/client/test";
    import Todo from "./Todo";

    const { mockApi } = mockServer();

    const mockTasks = [
      {
        id: 1,
        description: "test todo 1",
        isDone: true,
        userId: 1,
      },
    ];

    test("handles mock data", async () => {
      mockApi("/tasks", { res: mockTasks });

      renderInContext(<Todo />);

      await screen.findByText("test todo 1");

      expect(screen.getByRole("checkbox")).toBeChecked();

      screen.debug();
    });
    - - + + \ No newline at end of file diff --git a/docs/0.13.0/quick-start.html b/docs/0.13.0/quick-start.html index 3f8abc8b22..20c23074fe 100644 --- a/docs/0.13.0/quick-start.html +++ b/docs/0.13.0/quick-start.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.13.0

    Quick Start

    Installation​

    Welcome, new Waspeteer 🐝!

    Let's create and run our first Wasp app in 3 short steps:

    1. To install Wasp on Linux / OSX / WSL (Windows), open your terminal and run:

      curl -sSL https://get.wasp-lang.dev/installer.sh | sh

      ℹ️ Wasp requires Node.js and will warn you if it is missing: check below for more details.

    2. Then, create a new app by running:

      wasp new

    3. Finally, run the app:

      cd <my-project-name>
      wasp start

    That's it 🎉 You have successfully created and served a new full-stack web app at http://localhost:3000 and Wasp is serving both frontend and backend for you.

    Something Unclear?

    Check More Details section below if anything went wrong with the installation, or if you have additional questions.

    Want an even faster start?

    Try out Wasp AI 🤖 to generate a new Wasp app in minutes just from a title and short description!

    Try Wasp Without Installing 🤔?

    Give Wasp a spin in the browser with GitHub Codespaces by following the intructions in our Tutorial App README

    What next?​

    • 👉 Check out the Todo App tutorial, which will take you through all the core features of Wasp! 👈
    • Setup your editor for working with Wasp.
    • Join us on Discord! Any feedback or questions you have, we are there for you.
    • Follow Wasp development by subscribing to our newsletter: https://wasp-lang.dev/#signup . We usually send 1 per month, and Matija does his best to unleash his creativity to make them engaging and fun to read :D!

    More details​

    Requirements​

    You must have Node.js (and NPM) installed on your machine and available in PATH. A version of Node.js must be >= 18.

    If you need it, we recommend using nvm for managing your Node.js installation version(s).

    A quick guide on installing/using nvm

    Install nvm via your OS package manager (apt, pacman, homebrew, ...) or via the nvm install script.

    Then, install a version of Node.js that you need:

    nvm install 20

    Finally, whenever you need to ensure a specific version of Node.js is used, run:

    nvm use 20

    to set the Node.js version for the current shell session.

    You can run

    node -v

    to check the version of Node.js currently being used in this shell session.

    Check NVM repo for more details: https://github.com/nvm-sh/nvm.

    Installation​

    Open your terminal and run:

    curl -sSL https://get.wasp-lang.dev/installer.sh | sh
    Running Wasp on Mac with Mx chip (arm64)

    Experiencing the 'Bad CPU type in executable' issue on a device with arm64 (Apple Silicon)? Given that the wasp binary is built for x86 and not for arm64 (Apple Silicon), you'll need to install Rosetta on your Mac if you are using a Mac with Mx (M1, M2, ...). Rosetta is a translation process that enables users to run applications designed for x86 on arm64 (Apple Silicon). To install Rosetta, run the following command in your terminal

    softwareupdate --install-rosetta

    Once Rosetta is installed, you should be able to run Wasp without any issues.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/telemetry.html b/docs/0.13.0/telemetry.html index afff1995f0..9f2ba80fd9 100644 --- a/docs/0.13.0/telemetry.html +++ b/docs/0.13.0/telemetry.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.13.0

    Telemetry

    Overview​

    The term telemetry refers to the collection of certain usage data to help improve the quality of a piece of software (in this case, Wasp).

    Our telemetry implementation is anonymized and very limited in its scope, focused on answering following questions:

    • How many people and how often: tried to install Wasp, use Wasp, have built a Wasp app, or have deployed one?
    • How many projects are created with Wasp?

    When and what is sent?​

    • Information is sent via HTTPS request when wasp CLI command is invoked. Information is sent no more than twice in a period of 12 hours (sending is paused for 12 hours after last invocation, separately for wasp build command and for all other commands). Exact information as it is sent:
      {
        // Randomly generated, non-identifiable UUID representing a user.
        "distinct_id": "bf3fa7a8-1c11-4f82-9542-ec1a2d28786b",
        // Non-identifiable hash representing a project.
        "project_hash": "6d7e561d62b955d1",
        // True if command was `wasp build`, false otherwise.
        "is_build": true,
        // Captures `wasp deploy ...` args, but only those from the limited, pre-defined list of keywords.
        // Those are "fly", "setup", "create-db", "deploy" and "cmd". Everything else is ommited.
        "deploy_cmd_args": "fly;deploy",
        "wasp_version": "0.1.9.1",
        "os": "linux",
        // "CI" if running on CI, and whatever is the content of "WASP_TELEMETRY_CONTEXT" env var.
        // We use this to track when execution is happening in some special context, like on Gitpod, Replit or similar.
        "context": "CI"
      }
    • Information is also sent once via HTTPS request when wasp is installed via install.sh script. Exact information as it is sent:
      {
        // Randomly generated id.
        "distinct_id": "274701613078193779564259",
        "os": "linux"
      }

    Opting out​

    You sharing the telemetry data with us means a lot to us, since it helps us understand how popular Wasp is, how it is being used, how the changes we are doing affect usage, how many new vs old users there are, and just in general how Wasp is doing. We look at these numbers every morning and they drive us to make Wasp better.

    However, if you wish to opt-out of telemetry, we understand! You can do so by setting the WASP_TELEMETRY_DISABLE environment variable to any value, e.g.:

    export WASP_TELEMETRY_DISABLE=1

    Future plans​

    We don't have this implemented yet, but the next step will be to make telemetry go in two directions -> instead of just sending usage data to us, it will also at the same time check for any messages from our side (e.g. notification about new version of Wasp, or a security notice). Link to corresponding github issue.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/tutorial/actions.html b/docs/0.13.0/tutorial/actions.html index c22707f61b..c2374b75de 100644 --- a/docs/0.13.0/tutorial/actions.html +++ b/docs/0.13.0/tutorial/actions.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.13.0

    6. Modifying Data

    In the previous section, we learned about using Queries to fetch data and only briefly mentioned that Actions can be used to update the database. Let's learn more about Actions so we can add and update tasks in the database.

    We have to create:

    1. A Wasp Action that creates a new task.
    2. A React form that calls that Action when the user creates a task.

    Creating a New Action​

    Creating an Action is very similar to creating a Query.

    Declaring an Action​

    We must first declare the Action in main.wasp:

    main.wasp
    // ...

    action createTask {
      fn: import { createTask } from "@src/actions",
      entities: [Task]
    }

    Implementing an Action​

    Let's now define a function for our createTask Action:

    src/actions.js
    export const createTask = async (args, context) => {
      return context.entities.Task.create({
        data: { description: args.description },
      })
    }
    tip

    We put the function in a new file src/actions.ts, but we could have put it anywhere we wanted! There are no limitations here, as long as the declaration in the Wasp file imports it correctly and the file is located within src directory.

    Invoking the Action on the Client​

    Start by defining a form for creating new tasks.

    src/MainPage.jsx
    import { 
      createTask, 
      getTasks, 
      useQuery 
    } from 'wasp/client/operations'

    // ... MainPage, TaskView, TaskList ...

    const NewTaskForm = () => {
      const handleSubmit = async (event) => {
        event.preventDefault()
        try {
          const target = event.target
          const description = target.description.value
          target.reset()
          await createTask({ description })
        } catch (err) {
          window.alert('Error: ' + err.message)
        }
      }

      return (
        <form onSubmit={handleSubmit}>
          <input name="description" type="text" defaultValue="" />
          <input type="submit" value="Create task" />
        </form>
      )
    }

    Unlike Queries, you can call Actions directly (i.e., without wrapping it with a hook) because we don't need reactivity. The rest is just regular React code.

    All that's left now is adding this form to the page component:

    src/MainPage.jsx
    import {
      createTask,
      getTasks,
      useQuery
    } from 'wasp/client/operations'

    const MainPage = () => {
      const { data: tasks, isLoading, error } = useQuery(getTasks)

      return (
        <div>
          <NewTaskForm />

          {tasks && <TasksList tasks={tasks} />}

          {isLoading && 'Loading...'}
          {error && 'Error: ' + error}
        </div>
      )
    }

    // ... TaskView, TaskList, NewTaskForm ...

    Great work!

    You now have a form for creating new tasks.

    Try creating a "Build a Todo App in Wasp" task and see it appear in the list below. The task is created on the server and saved in the database.

    Try refreshing the page or opening it in another browser. You'll see the tasks are still there!

    Todo App - creating new task

    Automatic Query Invalidation

    When you create a new task, the list of tasks is automatically updated to display the new task, even though we have not written any code that would do that! Wasp handles these automatic updates under the hood.

    When you declared the getTasks and createTask operations, you specified that they both use the Task entity. So when createTask is called, Wasp knows that the data getTasks fetches may have changed and automatically updates it in the background. This means that out of the box, Wasp keeps all your queries in sync with any changes made through Actions.

    This behavior is convenient as a default but can cause poor performance in large apps. While there is no mechanism for overriding this behavior yet, it is something that we plan to include in Wasp in the future. This feature is tracked here.

    A Second Action​

    Our Todo app isn't finished if you can't mark a task as done.

    We'll create a new Action to update a task's status and call it from React whenever a task's checkbox is toggled.

    Since we've already created one task together, try to create this one yourself. It should be an Action named updateTask that receives the task's id and its isDone status. You can see our implementation below.

    Solution

    Declaring the Action in main.wasp:

    main.wasp
    // ...

    action updateTask {
      fn: import { updateTask } from "@src/actions",
      entities: [Task]
    }

    Implementing the Action on the server:

    src/actions.js
    // ...

    export const updateTask = async ({ id, isDone }, context) => {
      return context.entities.Task.update({
        where: { id },
        data: {
          isDone: isDone,
        },
      })
    }

    You can now call updateTask from the React component:

    src/MainPage.jsx
    // ...
    import {
      updateTask,
      createTask,
      getTasks,
      useQuery,
    } from 'wasp/client/operations'

    // ... MainPage ...

    const TaskView = ({ task }) => {
      const handleIsDoneChange = async (event) => {
        try {
          await updateTask({
            id: task.id,
            isDone: event.target.checked,
          })
        } catch (error) {
          window.alert('Error while updating task: ' + error.message)
        }
      }

      return (
        <div>
          <input
            type="checkbox"
            id={String(task.id)}
            checked={task.isDone}
            onChange={handleIsDoneChange}
          />
          {task.description}
        </div>
      )
    }
    // ... TaskList, NewTaskForm ...

    Awesome! You can now mark this task as done.

    It's time to make one final addition to your app: supporting multiple users.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/tutorial/auth.html b/docs/0.13.0/tutorial/auth.html index 1d80495128..d1339a483d 100644 --- a/docs/0.13.0/tutorial/auth.html +++ b/docs/0.13.0/tutorial/auth.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.13.0

    7. Adding Authentication

    Most modern apps need a way to create and authenticate users. Wasp makes this as easy as possible with its first-class auth support.

    To add users to your app, you must:

    • Create a User Entity.
    • Tell Wasp to use the Username and Password authentication.
    • Add login and signup pages.
    • Update the main page to require authentication.
    • Add a relation between User and Task entities.
    • Modify your Queries and Actions so users can only see and modify their tasks.
    • Add a logout button.

    Creating a User Entity​

    Since Wasp manages authentication, it will create the auth related entities for you in the background. Nothing to do here!

    You must only add the User Entity to keep track of who owns which tasks.

    main.wasp
    // ...

    entity User {=psl
        id       Int    @id @default(autoincrement())
    psl=}

    Adding Auth to the Project​

    Next, tell Wasp to use full-stack authentication:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "TodoApp",
      auth: {
        // Tells Wasp which entity to use for storing users.
        userEntity: User,
        methods: {
          // Enable username and password auth.
          usernameAndPassword: {}
        },
        // We'll see how this is used in a bit.
        onAuthFailedRedirectTo: "/login"
      }
    }

    // ...

    Don't forget to update the database schema by running:

    wasp db migrate-dev

    By doing this, Wasp will create:

    • Auth UI with login and signup forms.
    • A logout() action.
    • A React hook useAuth().
    • context.user for use in Queries and Actions.
    info

    Wasp also supports authentication using Google, GitHub, and email, with more on the way!

    Adding Login and Signup Pages​

    Wasp creates the login and signup forms for us, but we still need to define the pages to display those forms on. We'll start by declaring the pages in the Wasp file:

    main.wasp
    // ...

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage"
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage"
    }

    Great, Wasp now knows these pages exist!

    Here's the React code for the pages you've just imported:

    src/LoginPage.jsx
    import { Link } from 'react-router-dom'
    import { LoginForm } from 'wasp/client/auth'

    export const LoginPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <LoginForm />
          <br />
          <span>
            I don't have an account yet (<Link to="/signup">go to signup</Link>).
          </span>
        </div>
      )
    }

    The signup page is very similar to the login page:

    src/SignupPage.jsx
    import { Link } from 'react-router-dom'
    import { SignupForm } from 'wasp/client/auth'

    export const SignupPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <SignupForm />
          <br />
          <span>
            I already have an account (<Link to="/login">go to login</Link>).
          </span>
        </div>
      )
    }

    Update the Main Page to Require Auth​

    We don't want users who are not logged in to access the main page, because they won't be able to create any tasks. So let's make the page private by requiring the user to be logged in:

    main.wasp
    // ...

    page MainPage {
      authRequired: true,
      component: import { MainPage } from "@src/MainPage"
    }

    Now that auth is required for this page, unauthenticated users will be redirected to /login, as we specified with app.auth.onAuthFailedRedirectTo.

    Additionally, when authRequired is true, the page's React component will be provided a user object as prop.

    src/MainPage.jsx
    export const MainPage = ({ user }) => {
      // Do something with the user
      // ...
    }

    Ok, time to test this out. Navigate to the main page (/) of the app. You'll get redirected to /login, where you'll be asked to authenticate.

    Since we just added users, you don't have an account yet. Go to the signup page and create one. You'll be sent back to the main page where you will now be able to see the TODO list!

    Let's check out what the database looks like. Start the Prisma Studio:

    wasp db studio
    Database demonstration - password hashing

    You'll notice that we now have a User entity in the database alongside the Task entity.

    However, you will notice that if you try logging in as different users and creating some tasks, all users share the same tasks. That's because we haven't yet updated the queries and actions to have per-user tasks. Let's do that next.

    You might notice some extra Prisma models like Auth, AuthIdentity and Session that Wasp created for us. You don't need to care about these right now, but if you are curious, you can read more about them here.

    Defining a User-Task Relation​

    First, let's define a one-to-many relation between users and tasks (check the Prisma docs on relations):

    main.wasp
    // ...

    entity User {=psl
        id       Int    @id @default(autoincrement())
        tasks    Task[]
    psl=}

    entity Task {=psl
        id          Int     @id @default(autoincrement())
        description String
        isDone      Boolean @default(false)
        user        User?   @relation(fields: [userId], references: [id])
        userId      Int?
    psl=}

    // ...

    As always, you must migrate the database after changing the Entities:

    wasp db migrate-dev
    note

    We made user and userId in Task optional (via ?) because that allows us to keep the existing tasks, which don't have a user assigned, in the database.

    This isn't recommended because it allows an unwanted state in the database (what is the purpose of the task not belonging to anybody?) and normally we would not make these fields optional.

    Instead, we would do a data migration to take care of those tasks, even if it means just deleting them all. However, for this tutorial, for the sake of simplicity, we will stick with this.

    Updating Operations to Check Authentication​

    Next, let's update the queries and actions to forbid access to non-authenticated users and to operate only on the currently logged-in user's tasks:

    src/queries.js
    import { HttpError } from 'wasp/server'

    export const getTasks = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.findMany({
        where: { user: { id: context.user.id } },
        orderBy: { id: 'asc' },
      })
    }
    src/actions.js
    import { HttpError } from 'wasp/server'

    export const createTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.create({
        data: {
          description: args.description,
          user: { connect: { id: context.user.id } },
        },
      })
    }

    export const updateTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.updateMany({
        where: { id: args.id, user: { id: context.user.id } },
        data: { isDone: args.isDone },
      })
    }
    note

    Due to how Prisma works, we had to convert update to updateMany in updateTask action to be able to specify the user id in where.

    With these changes, each user should have a list of tasks that only they can see and edit.

    Try playing around, adding a few users and some tasks for each of them. Then open the DB studio:

    wasp db studio
    Database demonstration

    You will see that each user has their tasks, just as we specified in our code!

    Logout Button​

    Last, but not least, let's add the logout functionality:

    src/MainPage.jsx
    // ...
    import { logout } from 'wasp/client/auth'
    //...

    const MainPage = () => {
      // ...
      return (
        <div>
          // ...
          <button onClick={logout}>Logout</button>
        </div>
      )
    }

    This is it, we have a working authentication system, and our Todo app is multi-user!

    What's Next?​

    We did it 🎉 You've followed along with this tutorial to create a basic Todo app with Wasp.

    You should be ready to learn about more complicated features and go more in-depth with the features already covered. Scroll through the sidebar on the left side of the page to see every feature Wasp has to offer. Or, let your imagination run wild and start building your app! ✨

    Looking for inspiration?

    note

    If you notice that some of the features you'd like to have are missing, or have any other kind of feedback, please write to us on Discord or create an issue on Github, so we can learn which features to add/improve next 🙏

    If you would like to contribute or help to build a feature, let us know! You can find more details on contributing here.

    Oh, and do subscribe to our newsletter! We usually send one per month, and Matija does his best to unleash his creativity to make them engaging and fun to read :D!

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/tutorial/create.html b/docs/0.13.0/tutorial/create.html index a35cde220e..0b82845bba 100644 --- a/docs/0.13.0/tutorial/create.html +++ b/docs/0.13.0/tutorial/create.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.13.0

    1. Creating a New Project

    info

    You'll need to have the latest version of Wasp installed locally to follow this tutorial. If you haven't installed it yet, check out the QuickStart guide!

    In this section, we'll guide you through the process of creating a simple Todo app with Wasp. In the process, we'll take you through the most important and useful features of Wasp.

    How Todo App will work once it is done

    If you get stuck at any point (or just want to chat), reach out to us on Discord and we will help you!

    You can find the complete code of the app we're about to build here.

    Creating a Project​

    To setup a new Wasp project, run the following command in your terminal

    $ wasp new TodoApp

    Enter the newly created directory and start the development server:

    $ cd TodoApp
    $ wasp start
    note

    wasp start will take a bit of time to start the server the first time you run it in a new project.

    You will see log messages from the client, server, and database setting themselves up. When everything is ready, a new tab should open in your browser at http://localhost:3000 with a simple placeholder page:

    Screenshot of new Wasp app

    Wasp has generated for you the full front-end and back-end code the app! Next, we'll take a closer look at how the project is structured.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/tutorial/entities.html b/docs/0.13.0/tutorial/entities.html index 2dd72d1409..21a03429ff 100644 --- a/docs/0.13.0/tutorial/entities.html +++ b/docs/0.13.0/tutorial/entities.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.13.0

    4. Database Entities

    Entities are one of the most important concepts in Wasp and are how you define what gets stored in the database.

    Since our Todo app is all about tasks, we will define a Task entity in the Wasp file:

    main.wasp
    // ...

    entity Task {=psl
        id          Int     @id @default(autoincrement())
        description String
        isDone      Boolean @default(false)
    psl=}
    note

    Wasp uses Prisma as a way to talk to the database. You define entities by defining Prisma models using the Prisma Schema Language (PSL) between the {=psl psl=} tags.

    Read more in the Entities section of the docs.

    To update the database schema to include this entity, stop the wasp start process, if it's running, and run:

    wasp db migrate-dev

    You'll need to do this any time you change an entity's definition. It instructs Prisma to create a new database migration and apply it to the database.

    To take a look at the database and the new Task entity, run:

    wasp db studio

    This will open a new page in your browser to view and edit the data in your database.

    Todo App - Db studio showing Task schema

    Click on the Task entity and check out its fields! We don't have any data in our database yet, but we are about to change that.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/tutorial/pages.html b/docs/0.13.0/tutorial/pages.html index f4d3b057cc..68b845f647 100644 --- a/docs/0.13.0/tutorial/pages.html +++ b/docs/0.13.0/tutorial/pages.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.13.0

    3. Pages & Routes

    In the default main.wasp file created by wasp new, there is a page and a route declaration:

    main.wasp
    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      // We specify that the React implementation of the page is exported from 
      // `src/MainPage.jsx`. This statement uses standard JS import syntax.
      // Use `@src` to reference files inside the `src` folder.
      component: import { MainPage } from "@src/MainPage"
    }

    Together, these declarations tell Wasp that when a user navigates to /, it should render the named export from src/MainPage.tsx.

    The MainPage Component​

    Let's take a look at the React component referenced by the page declaration:

    src/MainPage.jsx
    import waspLogo from './waspLogo.png'
    import './Main.css'

    export const MainPage = () => {
      // ...
    }

    This is a regular functional React component. It also uses the CSS file and a logo image that sit next to it in the src folder.

    That is all the code you need! Wasp takes care of everything else necessary to define, build, and run the web app.

    tip

    wasp start automatically picks up the changes you make and restarts the app, so keep it running in the background.

    Adding a Second Page​

    To add more pages, you can create another set of page and route declarations. You can even add parameters to the URL path, using the same syntax as React Router. Let's test this out by adding a new page:

    main.wasp
    route HelloRoute { path: "/hello/:name", to: HelloPage }
    page HelloPage {
      component: import { HelloPage } from "@src/HelloPage"
    }

    When a user visits /hello/their-name, Wasp will render the component exported from src/HelloPage.tsx and pass the URL parameter the same way as in React Router:

    src/HelloPage.jsx
    export const HelloPage = (props) =>  {
      return <div>Here's {props.match.params.name}!</div>
    }

    Now you can visit /hello/johnny and see "Here's johnny!"

    Cleaning Up​

    Now that you've seen how Wasp deals with Routes and Pages, it's finally time to build the Todo app.

    Start by cleaning up the starter project and removing unnecessary code and files.

    First, remove most of the code from the MainPage component:

    src/MainPage.jsx
    export const MainPage = () => {
      return <div>Hello world!</div>
    }

    At this point, the main page should look like this:

    Todo App - Hello World

    You can now delete redundant files: src/Main.css, src/waspLogo.png, and src/HelloPage.tsx (we won't need this page for the rest of the tutorial).

    Since src/HelloPage.tsx no longer exists, remove its route and page declarations from the main.wasp file.

    Your Wasp file should now look like this:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.13.0"
      },
      title: "TodoApp"
    }

    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      component: import { MainPage } from "@src/MainPage"
    }

    Excellent work!

    You now have a basic understanding of Wasp and are ready to start building your TodoApp. We'll implement the app's core features in the following sections.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/tutorial/project-structure.html b/docs/0.13.0/tutorial/project-structure.html index 979a4df16c..75d2a512d9 100644 --- a/docs/0.13.0/tutorial/project-structure.html +++ b/docs/0.13.0/tutorial/project-structure.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ We'll keep it simple by placing everything in the root src directory.

    Many other files (e.g., tsconfig.json, vite-env.d.ts, .wasproot, etc.) help Wasp and the IDE improve your development experience with autocompletion, IntelliSense, and error reporting.

    The vite.config.ts file is used to configure Vite, Wasp's build tool of choice. We won't be configuring Vite in this tutorial, so you can safely ignore the file. Still, if you ever end up wanting more control over Vite, you'll find everything you need to know in custom Vite config docs.

    There's no need to spend more time discussing all the helper files. They'll silently do their job in the background and let you focus on building your app.

    TypeScript Support

    Wasp supports TypeScript out of the box, but you are free to choose between or mix JavaScript and TypeScript as you see fit.

    We'll provide you with both JavaScript and TypeScript code in this tutorial. Code blocks will have a toggle to switch between vanilla JavaScript and TypeScript.

    The most important file in the project is main.wasp. Wasp uses the configuration within it to perform its magic. Based on what you write, it generates a bunch of code for your database, server-client communication, React routing, and more.

    Let's take a closer look at main.wasp

    main.wasp​

    main.wasp is your app's definition file. It defines the app's central components and helps Wasp to do a lot of the legwork for you.

    The file is a list of declarations. Each declaration defines a part of your app.

    The default main.wasp file generated with wasp new on the previous page looks like this:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.13.0" // Pins the version of Wasp to use.
      },
      title: "TodoApp" // Used as the browser tab title. Note that all strings in Wasp are double quoted!
    }

    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      // We specify that the React implementation of the page is exported from
      // `src/MainPage.jsx`. This statement uses standard JS import syntax.
      // Use `@src` to reference files inside the `src` folder.
      component: import { MainPage } from "@src/MainPage"
    }

    This file uses three declaration types:

    • app: Top-level configuration information about your app.

    • route: Describes which path each page should be accessible from.

    • page: Defines a web page and the React component that gets rendered when the page is loaded.

    In the next section, we'll explore how route and page work together to build your web app.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/tutorial/queries.html b/docs/0.13.0/tutorial/queries.html index 89cf4d87b0..2084b9f0ac 100644 --- a/docs/0.13.0/tutorial/queries.html +++ b/docs/0.13.0/tutorial/queries.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.13.0

    5. Querying the Database

    We want to know which tasks we need to do, so let's list them!

    The primary way of working with Entities in Wasp is with Queries and Actions, collectively known as Operations.

    Queries are used to read an entity, while Actions are used to create, modify, and delete entities. Since we want to list the tasks, we'll want to use a Query.

    To list the tasks, you must:

    1. Create a Query that fetches the tasks from the database.
    2. Update the MainPage.tsx to use that Query and display the results.

    Defining the Query​

    We'll create a new Query called getTasks. We'll need to declare the Query in the Wasp file and write its implementation in .

    Declaring a Query​

    We need to add a query declaration to main.wasp so that Wasp knows it exists:

    main.wasp
    // ...

    query getTasks {
      // Specifies where the implementation for the query function is.
      // The path `@src/queries` resolves to `src/queries.js`.
      // No need to specify an extension.
      fn: import { getTasks } from "@src/queries",
      // Tell Wasp that this query reads from the `Task` entity. Wasp will
      // automatically update the results of this query when tasks are modified.
      entities: [Task]
    }

    Implementing a Query​

    src/queries.js
    export const getTasks = async (args, context) => {
      return context.entities.Task.findMany({
        orderBy: { id: 'asc' },
      })
    }

    Query function parameters:

    • args: object

      The arguments the caller passes to the Query.

    • context

      An object with extra information injected by Wasp. Its type depends on the Query declaration.

    Since the Query declaration in main.wasp says that the getTasks Query uses Task entity, Wasp injected a Prisma client for the Task entity as context.entities.Task - we used it above to fetch all the tasks from the database.

    info

    Queries and Actions are NodeJS functions executed on the server.

    Invoking the Query On the Frontend​

    While we implement Queries on the server, Wasp generates client-side functions that automatically take care of serialization, network calls, and cache invalidation, allowing you to call the server code like it's a regular function.

    This makes it easy for us to use the getTasks Query we just created in our React component:

    src/MainPage.jsx
    import { getTasks, useQuery } from 'wasp/client/operations'

    export const MainPage = () => {
      const { data: tasks, isLoading, error } = useQuery(getTasks)

      return (
        <div>
          {tasks && <TasksList tasks={tasks} />}

          {isLoading && 'Loading...'}
          {error && 'Error: ' + error}
        </div>
      )
    }

    const TaskView = ({ task }) => {
      return (
        <div>
          <input type="checkbox" id={String(task.id)} checked={task.isDone} />
          {task.description}
        </div>
      )
    }

    const TasksList = ({ tasks }) => {
      if (!tasks?.length) return <div>No tasks</div>

      return (
        <div>
          {tasks.map((task, idx) => (
            <TaskView task={task} key={idx} />
          ))}
        </div>
      )
    }

    Most of this code is regular React, the only exception being the special wasp imports:

    We could have called the Query directly using getTasks(), but the useQuery hook makes it reactive: React will re-render the component every time the Query changes. Remember that Wasp automatically refreshes Queries whenever the data is modified.

    With these changes, you should be seeing the text "No tasks" on the screen:

    Todo App - No Tasks

    We'll create a form to add tasks in the next step 🪄

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/vision.html b/docs/0.13.0/vision.html index f363d83718..f17a6ec509 100644 --- a/docs/0.13.0/vision.html +++ b/docs/0.13.0/vision.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -33,7 +33,7 @@ They can be used inline (mixed with Wasp code) or provided via external files.
  • Has hatches (escape mechanisms) that allow you to customize your web app in all the right places, but remain hidden until you need them.
  • Entity (data model) is a first-class citizen - defined via custom Wasp syntax and it integrates very closely with the rest of the features, serving as one of the central concepts around which everything is built.
  • Out of the box support for CRUD UI based on the Entities, to get you quickly going, but also customizable to some level.
  • "Smart" operations (queries and actions) that in most cases automatically figure out when to update, and if not it is easy to define custom logic to compensate for that. User worries about client-server gap as little as possible.
  • Support, directly in Wasp, for declaratively defining simple components and operations.
  • Besides Wasp as a programming language, there will also be a visual builder that generates/edits Wasp code, allowing non-developers to participate in development. Since Wasp is declarative, we imagine such builder to naturally follow from Wasp language.
  • Server side rendering, caching, packaging, security, ... -> all those are taken care of by Wasp. You tell Wasp what you want, and Wasp figures out how to do it.
  • As simple deployment to production/staging as it gets.
  • While it comes with the official implementation(s), Wasp language will not be coupled with the single implementation. Others can provide implementations that compile to different web app stacks.
    • - - + + \ No newline at end of file diff --git a/docs/0.13.0/wasp-ai/creating-new-app.html b/docs/0.13.0/wasp-ai/creating-new-app.html index 515f08c6be..7b1d4522d1 100644 --- a/docs/0.13.0/wasp-ai/creating-new-app.html +++ b/docs/0.13.0/wasp-ai/creating-new-app.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.13.0

    Creating New App with AI

    Wasp comes with its own AI: Wasp AI, aka Mage (Magic web App GEnerator).

    Wasp AI allows you to create a new Wasp app from only a title and a short description (using GPT in the background)!

    There are two main ways to create a new Wasp app with Wasp AI:

    1. Free, open-source online app usemage.ai.
    2. Running wasp new on your machine and picking AI generation. For this you need to provide your own OpenAI API keys, but it allows for more flexibility (choosing GPT models).

    They both use the same logic in the background, so both approaches are equally "smart", the difference is just in the UI / settings.

    info

    Wasp AI is an experimental feature. Apps that Wasp AI generates can have mistakes (proportional to their complexity), but even then they can often serve as a great starting point (once you fix the mistakes) or an interesting way to explore how to implement stuff in Wasp.

    usemage.ai​

    1. Describe your app 2. Pick the color 3. Generate your app 🚀

    Mage is an open-source app with which you can create new Wasp apps from just a short title and description.

    It is completely free for you - it uses our OpenAI API keys and we take on the costs.

    Once you provide an app title, app description, and choose some basic settings, your new Wasp app will be created for you in a matter of minutes and you will be able to download it to your machine and keep working on it!

    If you want to know more, check this blog post for more details on how Mage works, or this blog post for a high-level overview of how we implemented it.

    Wasp CLI​

    You can create a new Wasp app using Wasp AI by running wasp new in your terminal and picking AI generation.

    If you don't have them set yet, wasp will ask you to provide (via ENV vars) your OpenAI API keys (which it will use to query GPT).

    Then, after providing a title and description for your Wasp app, the new app will be generated on your disk!

    wasp-cli-ai-input wasp-cli-ai-generation

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/wasp-ai/developing-existing-app.html b/docs/0.13.0/wasp-ai/developing-existing-app.html index 149ff3d9b9..1adec30963 100644 --- a/docs/0.13.0/wasp-ai/developing-existing-app.html +++ b/docs/0.13.0/wasp-ai/developing-existing-app.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.13.0

    Developing Existing App with AI

    While Wasp AI doesn't at the moment offer any additional help for developing your Wasp app with AI beyond initial generation, this is something we are exploring actively.

    In the meantime, while waiting for Wasp AI to add support for this, we suggest checking out aider, which is an AI pair programming tool in your terminal. This is a third-party tool, not affiliated with Wasp in any way, but we and some of Wasp users have found that it can be helpful when working on Wasp apps.

    - - + + \ No newline at end of file diff --git a/docs/0.13.0/writingguide.html b/docs/0.13.0/writingguide.html index 4f300b809f..985bff05a5 100644 --- a/docs/0.13.0/writingguide.html +++ b/docs/0.13.0/writingguide.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -53,7 +53,7 @@ Many of our titles are currently in title-case, we should start phasing those out.
  • Use the Oxford comma (e.g., "a, b, and c" instead of "a, b and c"). Why the Oxford comma is important

    • 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/docs/0.14.0.html b/docs/0.14.0.html index 2493863720..ba2a78b894 100644 --- a/docs/0.14.0.html +++ b/docs/0.14.0.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ which are in their essence Node.js functions that execute on the server and can, thanks to Wasp, very easily be called from the client.

    First, we define these Operations in our main.wasp file, so Wasp knows about them and can "beef them up":

    main.wasp
    // Queries have automatic cache invalidation and are type-safe.
    query getRecipes {
      fn: import { getRecipes } from "@src/recipe/operations",
      entities: [Recipe],
    }

    // Actions are type-safe and can be used to perform side-effects.
    action addRecipe {
      fn: import { addRecipe } from "@src/recipe/operations",
      entities: [Recipe],
    }

    ... and then implement them in our Javascript (or TypeScript) code (we show just the query here, using TypeScript):

    src/recipe/operations.ts
    // Wasp generates the types for you.
    import { type GetRecipes } from "wasp/server/operations";
    import { type Recipe } from "wasp/entities";

    export const getRecipes: GetRecipes<{}, Recipe[]> = async (_args, context) => {
      return context.entities.Recipe.findMany( // Prisma query
        { where: { user: { id: context.user.id } } }
      );
    };

    export const addRecipe ...

    Now we can very easily use these in our React components!

    For the end, let's create a home page of our app.

    First, we define it in main.wasp:

    main.wasp
    ...

    route HomeRoute { path: "/", to: HomePage }
    page HomePage {
      component: import { HomePage } from "@src/pages/HomePage",
      authRequired: true // Will send user to /login if not authenticated.
    }

    and then implement it as a React component in JS/TS (that calls the Operations we previously defined):

    src/pages/HomePage.tsx
    import { useQuery, getRecipes } from "wasp/client/operations";
    import { type User } from "wasp/entities";

    export function HomePage({ user }: { user: User }) {
      // Due to full-stack type safety, `recipes` will be of type `Recipe[]` here.
      const { data: recipes, isLoading } = useQuery(getRecipes); // Calling our query here!

      if (isLoading) {
        return <div>Loading...</div>;
      }

      return (
        <div>
          <h1>Recipes</h1>
          <ul>
            {recipes ? recipes.map((recipe) => (
              <li key={recipe.id}>
                <div>{recipe.title}</div>
                <div>{recipe.description}</div>
              </li>
            )) : 'No recipes defined yet!'}
          </ul>
        </div>
      );
    }

    And voila! We are listing all the recipes in our app 🎉

    This was just a quick example to give you a taste of what Wasp is. For step by step tour through the most important Wasp features, check out the Todo app tutorial.

    note

    Above we skipped defining /login and /signup pages to keep the example a bit shorter, but those are very simple to do by using Wasp's Auth UI feature.

    When to use Wasp​

    Wasp addresses the same core problems that typical web app frameworks are addressing, and it in big part looks, swims and quacks like a web app framework.

    Best used for​

    • building full-stack web apps (like e.g. Airbnb or Asana)
    • quickly starting a web app with industry best practices
    • to be used alongside modern web dev stack (React and Node.js are currently supported)

    Avoid using Wasp for​

    • building static/presentational websites
    • to be used as a no-code solution
    • to be a solve-it-all tool in a single language

    Wasp is a DSL​

    note

    You don't need to know what a DSL is to use Wasp, but if you are curious, you can read more about it below.

    Wasp does not match typical expectations of a web app framework: it is not a set of libraries, it is instead a simple programming language that understands your code and can do a lot of things for you.

    Wasp is a programming language, but a specific kind: it is specialized for a single purpose: building modern web applications. We call such languages DSLs (Domain Specific Language).

    Other examples of DSLs that are often used today are e.g. SQL for databases and HTML for web page layouts. The main advantage and reason why DSLs exist is that they need to do only one task (e.g. database queries) so they can do it well and provide the best possible experience for the developer.

    The same idea stands behind Wasp - a language that will allow developers to build modern web applications with 10x less code and less stack-specific knowledge.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/advanced/accessing-app-config.html b/docs/0.14.0/advanced/accessing-app-config.html index 70307b3ecd..a6b0df2375 100644 --- a/docs/0.14.0/advanced/accessing-app-config.html +++ b/docs/0.14.0/advanced/accessing-app-config.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -36,7 +36,7 @@ Wasp automatically sets it during development when you run wasp start.
    In production, it should contain the value of your server's URL as the user's browser sees it (i.e., with the DNS and proxies considered).

    You can access it like this:

    import { config } from 'wasp/client'

    console.log(config.apiUrl)
    - - + + \ No newline at end of file diff --git a/docs/0.14.0/advanced/apis.html b/docs/0.14.0/advanced/apis.html index 3f2a23d5c1..acff54759e 100644 --- a/docs/0.14.0/advanced/apis.html +++ b/docs/0.14.0/advanced/apis.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.14.0

    Custom HTTP API Endpoints

    In Wasp, the default client-server interaction mechanism is through Operations. However, if you need a specific URL method/path, or a specific response, Operations may not be suitable for you. For these cases, you can use an api. Best of all, they should look and feel very familiar.

    How to Create an API​

    APIs are used to tie a JS function to a certain endpoint e.g. POST /something/special. They are distinct from Operations and have no client-side helpers (like useQuery).

    To create a Wasp API, you must:

    1. Declare the API in Wasp using the api declaration
    2. Define the API's NodeJS implementation

    After completing these two steps, you'll be able to call the API from the client code (via our Axios wrapper), or from the outside world.

    Declaring the API in Wasp​

    First, we need to declare the API in the Wasp file and you can easily do this with the api declaration:

    main.wasp
    // ...

    api fooBar { // APIs and their implementations don't need to (but can) have the same name.
      fn: import { fooBar } from "@src/apis",
      httpRoute: (GET, "/foo/bar")
    }

    Read more about the supported fields in the API Reference.

    Defining the API's NodeJS Implementation​

    After you defined the API, it should be implemented as a NodeJS function that takes three arguments:

    1. req: Express Request object
    2. res: Express Response object
    3. context: An additional context object injected into the API by Wasp. This object contains user session information, as well as information about entities. The examples here won't use the context for simplicity purposes. You can read more about it in the section about using entities in APIs.
    src/apis.js
    export const fooBar = (req, res, context) => {
      res.set("Access-Control-Allow-Origin", "*"); // Example of modifying headers to override Wasp default CORS middleware.
      res.json({ msg: `Hello, ${context.user ? "registered user" : "stranger"}!` });
    };

    Using the API​

    Using the API externally​

    To use the API externally, you simply call the endpoint using the method and path you used.

    For example, if your app is running at https://example.com then from the above you could issue a GET to https://example/com/foo/callback (in your browser, Postman, curl, another web service, etc.).

    Using the API from the Client​

    To use the API from your client, including with auth support, you can import the Axios wrapper from wasp/client/api and invoke a call. For example:

    src/pages/SomePage.jsx
    import React, { useEffect } from "react";
    import { api } from "wasp/client/api";

    async function fetchCustomRoute() {
      const res = await api.get("/foo/bar");
      console.log(res.data);
    }

    export const Foo = () => {
      useEffect(() => {
        fetchCustomRoute();
      }, []);

      return <>// ...</>;
    };

    Making Sure CORS Works​

    APIs are designed to be as flexible as possible, hence they don't utilize the default middleware like Operations do. As a result, to use these APIs on the client side, you must ensure that CORS (Cross-Origin Resource Sharing) is enabled.

    You can do this by defining custom middleware for your APIs in the Wasp file.

    For example, an apiNamespace is a simple declaration used to apply some middlewareConfigFn to all APIs under some specific path:

    main.wasp
    apiNamespace fooBar {
      middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@src/apis",
      path: "/foo"
    }

    And then in the implementation file:

    src/apis.js
    export const apiMiddleware = (config) => {
      return config;
    };

    We are returning the default middleware which enables CORS for all APIs under the /foo path.

    For more information about middleware configuration, please see: Middleware Configuration

    Using Entities in APIs​

    In many cases, resources used in APIs will be Entities. To use an Entity in your API, add it to the api declaration in Wasp:

    main.wasp
    api fooBar {
      fn: import { fooBar } from "@src/apis",
      entities: [Task],
      httpRoute: (GET, "/foo/bar")
    }

    Wasp will inject the specified Entity into the APIs context argument, giving you access to the Entity's Prisma API:

    src/apis.js
    export const fooBar = (req, res, context) => {
      res.json({ count: await context.entities.Task.count() });
    };

    The object context.entities.Task exposes prisma.task from Prisma's CRUD API.

    API Reference​

    main.wasp
    api fooBar {
      fn: import { fooBar } from "@src/apis",
      httpRoute: (GET, "/foo/bar"),
      entities: [Task],
      auth: true,
      middlewareConfigFn: import { apiMiddleware } from "@src/apis"
    }

    The api declaration has the following fields:

    • fn: ExtImport required

      The import statement of the APIs NodeJs implementation.

    • httpRoute: (HttpMethod, string) required

      The HTTP (method, path) pair, where the method can be one of:

      • ALL, GET, POST, PUT or DELETE
      • and path is an Express path string.

    • entities: [Entity]

      A list of entities you wish to use inside your API. You can read more about it here.

    • auth: bool

      If auth is enabled, this will default to true and provide a context.user object. If you do not wish to attempt to parse the JWT in the Authorization Header, you should set this to false.

    • middlewareConfigFn: ExtImport

      The import statement to an Express middleware config function for this API. See more in middleware section of the docs.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/advanced/deployment/cli.html b/docs/0.14.0/advanced/deployment/cli.html index 3f96460431..f633e0d30d 100644 --- a/docs/0.14.0/advanced/deployment/cli.html +++ b/docs/0.14.0/advanced/deployment/cli.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ The command automates the manual deployment process and is the recommended way of deploying Wasp apps.

    Supported Providers​

    Wasp supports automated deployment to the following providers:

    • Fly.io - they offer 5$ free credit each month
    • Railway (coming soon, track it here #1157)

    Fly.io​

    Prerequisites​

    Fly provides free allowances for up to 3 VMs (so deploying a Wasp app to a new account is free), but all plans require you to add your credit card information before you can proceed. If you don't, the deployment will fail.

    You can add the required credit card information on the account's billing page.

    Fly.io CLI

    You will need the flyctl CLI installed on your machine before you can deploy to Fly.io.

    Deploying​

    Using the Wasp CLI, you can easily deploy a new app to Fly.io with just a single command:

    wasp deploy fly launch my-wasp-app mia
    Specifying Org

    If your account is a member of more than one organization on Fly.io, you will need to specify under which one you want to execute the command. To do that, provide an additional --org <org-slug> option. You can find out the names(slugs) of your organizations by running fly orgs list.

    Please do not CTRL-C or exit your terminal while the commands are running.

    Under the covers, this runs the equivalent of the following commands:

    wasp deploy fly setup my-wasp-app mia
    wasp deploy fly create-db mia
    wasp deploy fly deploy

    The commands above use the app basename my-wasp-app and deploy it to the Miami, Florida (US) region (called mia). Read more about Fly.io regions here.

    Unique Name

    Your app name must be unique across all of Fly or deployment will fail.

    The basename is used to create all three app tiers, resulting in three separate apps in your Fly dashboard:

    • my-wasp-app-client
    • my-wasp-app-server
    • my-wasp-app-db

    You'll notice that Wasp creates two new files in your project root directory:

    • fly-server.toml
    • fly-client.toml

    You should include these files in your version control so that you can deploy your app with a single command in the future.

    Using a Custom Domain For Your App​

    Setting up a custom domain is a three-step process:

    1. You need to add your domain to your Fly client app. You can do this by running:
    wasp deploy fly cmd --context client certs create mycoolapp.com
    Use Your Domain

    Make sure to replace mycoolapp.com with your domain in all of the commands mentioned in this section.

    This command will output the instructions to add the DNS records to your domain. It will look something like this:

    You can direct traffic to mycoolapp.com by:

    1: Adding an A record to your DNS service which reads

        A @ 66.241.1XX.154

    You can validate your ownership of mycoolapp.com by:

    2: Adding an AAAA record to your DNS service which reads:

        AAAA @ 2a09:82XX:1::1:ff40

    1. You need to add the DNS records for your domain:

      This will depend on your domain provider, but it should be a matter of adding an A record for @ and an AAAA record for @ with the values provided by the previous command.

    2. You need to set your domain as the WASP_WEB_CLIENT_URL environment variable for your server app:

    wasp deploy fly cmd --context server secrets set WASP_WEB_CLIENT_URL=https://mycoolapp.com

    We need to do this to keep our CORS configuration up to date.

    That's it, your app should be available at https://mycoolapp.com! 🎉

    Adding www Subdomain​

    If you'd like to also access your app at https://www.mycoolapp.com, you can generate certs for the www subdomain. 

    wasp deploy fly cmd --context client certs create www.mycoolapp.com

    Once you do that, you will need to add another DNS record for your domain. It should be a CNAME record for www with the value of your root domain. Here's an example:

    TypeNameValueTTL
    CNAMEwwwmycoolapp.com3600

    With the CNAME record (Canonical name), you are assigning the www subdomain as an alias to the root domain.

    Your app should now be available both at the root domain https://mycoolapp.com and the www sub-domain https://www.mycoolapp.com! 🎉

    API Reference​

    launch​

    launch is a convenience command that runs setup, create-db, and deploy in sequence.

    wasp deploy fly launch <app-name> <region>

    It accepts the following arguments:

    • <app-name> - the name of your app required

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    It gives you the same result as running the following commands:

    wasp deploy fly setup <app-name> <region>
    wasp deploy fly create-db <region>
    wasp deploy fly deploy

    Environment Variables​

    Server​

    If you are deploying an app that requires any other environment variables (like social auth secrets), you can set them with the --server-secret option:

    wasp deploy fly launch my-wasp-app mia --server-secret GOOGLE_CLIENT_ID=<...> --server-secret GOOGLE_CLIENT_SECRET=<...>
    Client​

    If you've added any client-side environment variables to your app, make sure to pass them to the terminal session before running the launch command, e.g.:

    REACT_APP_ANOTHER_VAR=somevalue wasp deploy fly launch my-wasp-app mia

    setup​

    setup will create your client and server apps on Fly, and add some secrets, but does not deploy them.

    wasp deploy fly setup <app-name> <region>

    It accepts the following arguments:

    • <app-name> - the name of your app required

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    After running setup, Wasp creates two new files in your project root directory: fly-server.toml and fly-client.toml. You should include these files in your version control.

    You can edit the fly-server.toml and fly-client.toml files to further configure your Fly deployments. Wasp will use the TOML files when you run deploy.

    If you want to maintain multiple apps, you can add the --fly-toml-dir <abs-path> option to point to different directories, like "dev" or "staging".

    Execute Only Once

    You should only run setup once per app. If you run it multiple times, it will create unnecessary apps on Fly.

    create-db​

    create-db will create a new database for your app.

    wasp deploy fly create-db <region>

    It accepts the following arguments:

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    Execute Only Once

    You should only run create-db once per app. If you run it multiple times, it will create multiple databases, but your app needs only one.

    deploy​

    wasp deploy fly deploy

    deploy pushes your client and server live.

    Run this command whenever you want to update your deployed app with the latest changes:

    wasp deploy fly deploy

    If you've added any client-side environment variables to your app, make sure to pass them to the terminal session before running the deploy command, e.g.:

    REACT_APP_ANOTHER_VAR=somevalue wasp deploy fly deploy

    Make sure to add your client-side environment variables every time you redeploy with the above command to ensure they are included in the build process!

    cmd​

    If want to run arbitrary Fly commands (e.g. flyctl secrets list for your server app), here's how to do it:

    wasp deploy fly cmd secrets list --context server

    Environment Variables​

    Server Secrets​

    If your app requires any other server-side environment variables (like social auth secrets), you can set them:

    1. initially in the launch command with the --server-secret option,
      or
    2. after the app has already been deployed by using the secrets set command:
    wasp deploy fly cmd secrets set GOOGLE_CLIENT_ID=<...> GOOGLE_CLIENT_SECRET=<...> --context=server

    Client Environment Variables​

    If you've added any client-side environment variables to your app, make sure to pass them to the terminal session before running a deployment command, e.g.:

    REACT_APP_ANOTHER_VAR=somevalue wasp deploy fly launch my-wasp-app mia

    or 

    REACT_APP_ANOTHER_VAR=somevalue wasp deploy fly deploy

    Fly.io Regions​

    Fly.io runs applications physically close to users: in datacenters around the world, on servers we run ourselves. You can currently deploy your apps in 34 regions, connected to a global Anycast network that makes sure your users hit our nearest server, whether they’re in Tokyo, São Paolo, or Frankfurt.

    Read more on Fly regions here.

    You can find the list of all available Fly regions by running:

    flyctl platform regions

    Multiple Fly.io Organizations​

    If you have multiple organizations, you can specify a --org option. For example:

    wasp deploy fly launch my-wasp-app mia --org hive

    Building Locally​

    Fly.io offers support for both locally built Docker containers and remotely built ones. However, for simplicity and reproducibility, the CLI defaults to the use of a remote Fly.io builder.

    If you want to build locally, supply the --build-locally option to wasp deploy fly launch or wasp deploy fly deploy.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/advanced/deployment/manually.html b/docs/0.14.0/advanced/deployment/manually.html index 836ca4e537..4d59ed30e6 100644 --- a/docs/0.14.0/advanced/deployment/manually.html +++ b/docs/0.14.0/advanced/deployment/manually.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -40,7 +40,7 @@ Set it to a random string at least 32 characters long (you can use an online generator).

  • PORT

    The server's HTTP port number. This is where the server listens for requests (default: 3001).

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

    Client Environment Variables

    Remember, if you have manually defined any other client-side environment variables in your project, make sure to add them to the command above when building your client

    The command above will build the web client and put it in the build/ directory in the .wasp/build/web-app/.

    This is also the moment to provide any additional env vars for the client code, next to REACT_APP_API_URL. Check the env vars docs for more details.

    Since the result of building is just a bunch of static files, you can now deploy your web client to any static hosting provider (e.g. Netlify, Cloudflare, ...) by deploying the contents of .wasp/build/web-app/build/.

    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, add a few more environment variables for the server code.

    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.

    Client Environment Variables

    Remember, if you have manually defined any other client-side environment variables in your project, make sure to add them to the command above when building your client

    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). https:// prefix is required!

      • add WASP_SERVER_URL - enter the server domain (e.g. https://server-production-XXXX.up.railway.app). https:// prefix is required!

      • 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/0.14.0/advanced/deployment/overview.html b/docs/0.14.0/advanced/deployment/overview.html index c0eccdf386..9aea9e5185 100644 --- a/docs/0.14.0/advanced/deployment/overview.html +++ b/docs/0.14.0/advanced/deployment/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ 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.14.0/advanced/email.html b/docs/0.14.0/advanced/email.html index 72fbb8e1be..093ab89de2 100644 --- a/docs/0.14.0/advanced/email.html +++ b/docs/0.14.0/advanced/email.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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.14.0/advanced/jobs.html b/docs/0.14.0/advanced/jobs.html index 47f46a056f..0b726793cb 100644 --- a/docs/0.14.0/advanced/jobs.html +++ b/docs/0.14.0/advanced/jobs.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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 that your database provider is set to "postgresql" in your schema.prisma file. Read more about setting the provider here.

      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.14.0/advanced/links.html b/docs/0.14.0/advanced/links.html index 64345c9e18..4126852492 100644 --- a/docs/0.14.0/advanced/links.html +++ b/docs/0.14.0/advanced/links.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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.14.0/advanced/middleware-config.html b/docs/0.14.0/advanced/middleware-config.html index 3e029e8935..507b2dd59a 100644 --- a/docs/0.14.0/advanced/middleware-config.html +++ b/docs/0.14.0/advanced/middleware-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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/0.14.0/advanced/web-sockets.html b/docs/0.14.0/advanced/web-sockets.html index 3ff8b7ffd2..6621115ae1 100644 --- a/docs/0.14.0/advanced/web-sockets.html +++ b/docs/0.14.0/advanced/web-sockets.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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​

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

    The 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.14.0/auth/auth-hooks.html b/docs/0.14.0/auth/auth-hooks.html index 8709d22de8..91b64156e8 100644 --- a/docs/0.14.0/auth/auth-hooks.html +++ b/docs/0.14.0/auth/auth-hooks.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.0

    Auth Hooks

    Auth hooks allow you to "hook into" the auth process at various stages and run your custom code. For example, if you want to forbid certain emails from signing up, or if you wish to send a welcome email to the user after they sign up, auth hooks are the way to go.

    Supported hooks​

    The following auth hooks are available in Wasp:

    We'll go through each of these hooks in detail. But first, let's see how the hooks fit into the auth flows:

    Signup Flow with Hooks
    Signup Flow with Hooks

    Login Flow with Hooks
    Login Flow with Hooks *

    * When using the OAuth auth providers, the login hooks are both called before the session is created but the session is created quickly afterward, so it shouldn't make any difference in practice.

    If you are using OAuth, the flow includes extra steps before the auth flow:

    OAuth Flow with Hooks
    OAuth Flow with Hooks

    Using hooks​

    To use auth hooks, you must first declare them in the Wasp file:

    app myApp {
      wasp: {
        version: "^0.14.0"
      },
      auth: {
        userEntity: User,
        methods: {
          ...
        },
        onBeforeSignup: import { onBeforeSignup } from "@src/auth/hooks",
        onAfterSignup: import { onAfterSignup } from "@src/auth/hooks",
        onBeforeOAuthRedirect: import { onBeforeOAuthRedirect } from "@src/auth/hooks",
        onBeforeLogin: import { onBeforeLogin } from "@src/auth/hooks",
        onAfterLogin: import { onAfterLogin } from "@src/auth/hooks",
      },
    }

    If the hooks are defined as async functions, Wasp awaits them. This means the auth process waits for the hooks to finish before continuing.

    Wasp ignores the hooks' return values. The only exception is the onBeforeOAuthRedirect hook, whose return value affects the OAuth redirect URL.

    We'll now go through each of the available hooks.

    Executing code before the user signs up​

    Wasp calls the onBeforeSignup hook before the user is created.

    The onBeforeSignup hook can be useful if you want to reject a user based on some criteria before they sign up.

    Works with Email Username & Password Discord Github Google Keycloak

    main.wasp
    app myApp {
      ...
      auth: {
        ...
        onBeforeSignup: import { onBeforeSignup } from "@src/auth/hooks",
      },
    }
    src/auth/hooks.js
    import { HttpError } from 'wasp/server'

    export const onBeforeSignup = async ({ providerId, prisma, req }) => {
      const count = await prisma.user.count()
      console.log('number of users before', count)
      console.log('provider name', providerId.providerName)
      console.log('provider user ID', providerId.providerUserId)

      if (count > 100) {
        throw new HttpError(403, 'Too many users')
      }

      if (
        providerId.providerName === 'email' &&
        providerId.providerUserId === 'some@email.com'
      ) {
        throw new HttpError(403, 'This email is not allowed')
      }
    }

    Read more about the data the onBeforeSignup hook receives in the API Reference.

    Executing code after the user signs up​

    Wasp calls the onAfterSignup hook after the user is created.

    The onAfterSignup hook can be useful if you want to send the user a welcome email or perform some other action after the user signs up like syncing the user with a third-party service.

    Since the onAfterSignup hook receives the OAuth tokens, you can use this hook to store the OAuth access token and/or refresh token in your database.

    Works with Email Username & Password Discord Github Google Keycloak

    main.wasp
    app myApp {
      ...
      auth: {
        ...
        onAfterSignup: import { onAfterSignup } from "@src/auth/hooks",
      },
    }
    src/auth/hooks.js
    export const onAfterSignup = async ({
      providerId,
      user,
      oauth,
      prisma,
      req,
    }) => {
      const count = await prisma.user.count()
      console.log('number of users after', count)
      console.log('user object', user)

      // If this is an OAuth signup, you have access to the OAuth tokens and the uniqueRequestId
      if (oauth) {
        console.log('accessToken', oauth.tokens.accessToken)
        console.log('uniqueRequestId', oauth.uniqueRequestId)

        const id = oauth.uniqueRequestId
        const data = someKindOfStore.get(id)
        if (data) {
          console.log('saved data for the ID', data)
        }
        someKindOfStore.delete(id)
      }
    }

    Read more about the data the onAfterSignup hook receives in the API Reference.

    Executing code before the OAuth redirect​

    Wasp calls the onBeforeOAuthRedirect hook after the OAuth redirect URL is generated but before redirecting the user. This hook can access the request object sent from the client at the start of the OAuth process.

    The onBeforeOAuthRedirect hook can be useful if you want to save some data (e.g. request query parameters) that you can use later in the OAuth flow. You can use the uniqueRequestId parameter to reference this data later in the onAfterSignup or onAfterLogin hooks.

    Works with Discord Github Google Keycloak

    main.wasp
    app myApp {
      ...
      auth: {
        ...
        onBeforeOAuthRedirect: import { onBeforeOAuthRedirect } from "@src/auth/hooks",
      },
    }
    src/auth/hooks.js
    export const onBeforeOAuthRedirect = async ({ url, oauth, prisma, req }) => {
      console.log('query params before oAuth redirect', req.query)

      // Saving query params for later use in onAfterSignup or onAfterLogin hooks
      const id = oauth.uniqueRequestId
      someKindOfStore.set(id, req.query)

      return { url }
    }

    This hook's return value must be an object that looks like this: { url: URL }. Wasp uses the URL to redirect the user to the OAuth provider.

    Read more about the data the onBeforeOAuthRedirect hook receives in the API Reference.

    Executing code before the user logs in​

    Wasp calls the onBeforeLogin hook before the user is logged in.

    The onBeforeLogin hook can be useful if you want to reject a user based on some criteria before they log in.

    Works with Email Username & Password Discord Github Google Keycloak

    main.wasp
    app myApp {
      ...
      auth: {
        ...
        onBeforeLogin: import { onBeforeLogin } from "@src/auth/hooks",
      },
    }
    src/auth/hooks.js
    import { HttpError } from 'wasp/server'

    export const onBeforeLogin = async ({ providerId, user, prisma, req }) => {
      if (
        providerId.providerName === 'email' &&
        providerId.providerUserId === 'some@email.com'
      ) {
        throw new HttpError(403, 'You cannot log in with this email')
      }
    }

    Read more about the data the onBeforeLogin hook receives in the API Reference.

    Executing code after the user logs in​

    Wasp calls the onAfterLogin hook after the user logs in.

    The onAfterLogin hook can be useful if you want to perform some action after the user logs in, like syncing the user with a third-party service.

    Since the onAfterLogin hook receives the OAuth tokens, you can use it to update the OAuth access token for the user in your database. You can also use it to refresh the OAuth access token if the provider supports it.

    Works with Email Username & Password Discord Github Google Keycloak

    main.wasp
    app myApp {
      ...
      auth: {
        ...
        onAfterLogin: import { onAfterLogin } from "@src/auth/hooks",
      },
    }
    src/auth/hooks.js
    export const onAfterLogin = async ({
      providerId,
      user,
      oauth,
      prisma,
      req,
    }) => {
      console.log('user object', user)

      // If this is an OAuth signup, you have access to the OAuth tokens and the uniqueRequestId
      if (oauth) {
        console.log('accessToken', oauth.tokens.accessToken)
        console.log('uniqueRequestId', oauth.uniqueRequestId)

        const id = oauth.uniqueRequestId
        const data = someKindOfStore.get(id)
        if (data) {
          console.log('saved data for the ID', data)
        }
        someKindOfStore.delete(id)
      }
    }

    Read more about the data the onAfterLogin hook receives in the API Reference.

    Refreshing the OAuth access token​

    Some OAuth providers support refreshing the access token when it expires. To refresh the access token, you need the OAuth refresh token.

    Wasp exposes the OAuth refresh token in the onAfterSignup and onAfterLogin hooks. You can store the refresh token in your database and use it to refresh the access token when it expires.

    Import the provider object with the OAuth client from the wasp/server/auth module. For example, to refresh the Google OAuth access token, import the google object from the wasp/server/auth module. You use the refreshAccessToken method of the OAuth client to refresh the access token.

    Here's an example of how you can refresh the access token for Google OAuth:

    src/auth/hooks.js
    import { google } from 'wasp/server/auth'

    export const onAfterLogin = async ({ oauth }) => {
      if (oauth.provider === 'google' && oauth.tokens.refreshToken !== null) {
        const newTokens = await google.oAuthClient.refreshAccessToken(
          oauth.tokens.refreshToken
        )
        log('new tokens', newTokens)
      }
    }

    Google exposes the accessTokenExpiresAt field in the oauth.tokens object. You can use this field to determine when the access token expires.

    If you want to refresh the token periodically, use a Wasp Job.

    API Reference​

    app myApp {
      wasp: {
        version: "^0.14.0"
      },
      auth: {
        userEntity: User,
        methods: {
          ...
        },
        onBeforeSignup: import { onBeforeSignup } from "@src/auth/hooks",
        onAfterSignup: import { onAfterSignup } from "@src/auth/hooks",
        onBeforeOAuthRedirect: import { onBeforeOAuthRedirect } from "@src/auth/hooks",
        onBeforeLogin: import { onBeforeLogin } from "@src/auth/hooks",
        onAfterLogin: import { onAfterLogin } from "@src/auth/hooks",
      },
    }

    Common hook input​

    The following properties are available in all auth hooks:

    • prisma: PrismaClient

      The Prisma client instance which you can use to query your database.

    • req: Request

      The Express request object from which you can access the request headers, cookies, etc.

    The onBeforeSignup hook​

    src/auth/hooks.js
    export const onBeforeSignup = async ({ providerId, prisma, req }) => {
      // Hook code goes here
    }

    The hook receives an object as input with the following properties:

    Wasp ignores this hook's return value.

    The onAfterSignup hook​

    src/auth/hooks.js
    export const onAfterSignup = async ({
      providerId,
      user,
      oauth,
      prisma,
      req,
    }) => {
      // Hook code goes here
    }

    The hook receives an object as input with the following properties:

    Wasp ignores this hook's return value.

    The onBeforeOAuthRedirect hook​

    src/auth/hooks.js
    export const onBeforeOAuthRedirect = async ({ url, oauth, prisma, req }) => {
      // Hook code goes here

      return { url }
    }

    The hook receives an object as input with the following properties:

    • url: URL

      Wasp uses the URL for the OAuth redirect.

    • oauth: { uniqueRequestId: string }

      The oauth object has the following fields:

      • uniqueRequestId: string

        The unique request ID for the OAuth flow (you might know it as the state parameter in OAuth.)

        You can use the unique request ID to save data (e.g. request query params) that you can later use in the onAfterSignup or onAfterLogin hooks.

    • Plus the common hook input

    This hook's return value must be an object that looks like this: { url: URL }. Wasp uses the URL to redirect the user to the OAuth provider.

    The onBeforeLogin hook​

    src/auth/hooks.js
    export const onBeforeLogin = async ({ providerId, prisma, req }) => {
      // Hook code goes here
    }

    The hook receives an object as input with the following properties:

    Wasp ignores this hook's return value.

    The onAfterLogin hook​

    src/auth/hooks.js
    export const onAfterLogin = async ({
      providerId,
      user,
      oauth,
      prisma,
      req,
    }) => {
      // Hook code goes here
    }

    The hook receives an object as input with the following properties:

    Wasp ignores this hook's return value.

    ProviderId fields​

    The providerId object represents the user for the current authentication method. Wasp passes it to the onBeforeSignup, onAfterSignup, onBeforeLogin, and onAfterLogin hooks.

    It has the following fields:

    • providerName: string

      The provider's name (e.g. 'email', 'google', 'github)

    • providerUserId: string

      The user's unique ID in the provider's system (e.g. email, Google ID, GitHub ID)

    OAuth fields​

    Wasp passes the oauth object to the onAfterSignup and onAfterLogin hooks only when the user is authenticated with Social Auth.

    It has the following fields:

    • providerName: string

      The name of the OAuth provider the user authenticated with (e.g. 'google', 'github').

    • tokens: Tokens

      You can use the OAuth tokens to make requests to the provider's API on the user's behalf.

      Depending on the OAuth provider, the tokens object might have different fields. For example, Google has the fields accessToken, refreshToken, idToken, and accessTokenExpiresAt.

    • uniqueRequestId: string

      The unique request ID for the OAuth flow (you might know it as the state parameter in OAuth.)

      You can use the unique request ID to get the data that was saved in the onBeforeOAuthRedirect hook.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/auth/email.html b/docs/0.14.0/auth/email.html index 97bce8fded..fff7ff0e18 100644 --- a/docs/0.14.0/auth/email.html +++ b/docs/0.14.0/auth/email.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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 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.14.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:

    schema.prisma
    // 5. Define the user entity
    model User {
      id Int @id @default(autoincrement())
      // Add your own fields below
      // ...
    }

    You can read more about how the User is connected to the rest of the auth system and how you can access the user data in the Accessing User Data 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
    // ...

    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.

    When you receive the user object on the client or the server, you'll be able to access the user's email and other information like this:

    const emailIdentity = user.identities.email

    // Email address the the user used to sign up, e.g. "fluffyllama@app.com".
    emailIdentity.id

    // `true` if the user has verified their email address.
    emailIdentity.isEmailVerified

    // Datetime when the email verification email was sent.
    emailIdentity.emailVerificationSentAt

    // Datetime when the last password reset email was sent.
    emailIdentity.passwordResetSentAt

    Read more about accessing the user data in the Accessing User Data section of the docs.

    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"
      },
      // ...
    }
    schema.prisma
    model User {
      id Int @id @default(autoincrement())
    }

    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.

    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.14.0/auth/entities.html b/docs/0.14.0/auth/entities.html index 2a2cc2b626..4eb5e4b26a 100644 --- a/docs/0.14.0/auth/entities.html +++ b/docs/0.14.0/auth/entities.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.0

    Accessing User Data

    First, we'll check out the most practical info: how to access the user's data in your app.

    Then, we'll dive into the details of the auth entities that Wasp creates behind the scenes to store the user's data. For auth each method, Wasp needs to store different information about the user. For example, username for Username & password auth, email verification status for Email auth, and so on.

    We'll also show you how you can use these entities to create a custom signup action.

    Accessing the Auth Fields​

    When you receive the user object on the client or the server, it will contain all the user fields you defined in the User entity in the schema.prisma file. In addition to that, it will also contain all the auth-related fields that Wasp stores. This includes things like the username or the email verification status. In Wasp, this data is called the AuthUser object.

    AuthUser Object Fields​

    All the User fields you defined will be present at the top level of the AuthUser object. The auth-related fields will be on the identities object. For each auth method you enable, there will be a separate data object in the identities object.

    The AuthUser object will change depending on which auth method you have enabled in the Wasp file. For example, if you enabled the email auth and Google auth, it would look something like this:

    If the user has only the Google identity, the AuthUser object will look like this:

    const user = {
      // User data
      id: 'cluqs9qyh00007cn73apj4hp7',
      address: 'Some address',

      // Auth methods specific data
      identities: {
        email: null,
        google: {
          id: '1117XXXX1301972049448',
        },
      },
    }

    In the examples above, you can see the identities object contains the email and google objects. The email object contains the email-related data and the google object contains the Google-related data.

    Make sure to check if the data exists

    Before accessing some auth method's data, you'll need to check if that data exists for the user and then access it:

    if (user.identities.google !== null) {
      const userId = user.identities.google.id
      // ...
    }

    You need to do this because if a user didn't sign up with some auth method, the data for that auth method will be null.

    Let's look at the data for each of the available auth methods:

    • Username & password data

      const usernameIdentity = user.identities.username

      // Username that the user used to sign up, e.g. "fluffyllama"
      usernameIdentity.id

    • Email data

      const emailIdentity = user.identities.email

      // Email address the the user used to sign up, e.g. "fluffyllama@app.com".
      emailIdentity.id

      // `true` if the user has verified their email address.
      emailIdentity.isEmailVerified

      // Datetime when the email verification email was sent.
      emailIdentity.emailVerificationSentAt

      // Datetime when the last password reset email was sent.
      emailIdentity.passwordResetSentAt

    • Google data

      const googleIdentity = user.identities.google

      // Google User ID for example "123456789012345678901"
      googleIdentity.id

    • GitHub data

      const githubIdentity = user.identities.github

      // GitHub User ID for example "12345678"
      githubIdentity.id

    • Keycloak data

      const keycloakIdentity = user.identities.keycloak

      // Keycloak User ID for example "12345678-1234-1234-1234-123456789012"
      keycloakIdentity.id

    • Discord data

      const discordIdentity = user.identities.discord

      // Discord User ID for example "80351110224678912"
      discordIdentity.id

    If you support multiple auth methods, you'll need to find which identity exists for the user and then access its data:

    if (user.identities.email !== null) {
      const email = user.identities.email.id
      // ...
    } else if (user.identities.google !== null) {
      const googleId = user.identities.google.id
      // ...
    }

    getFirstProviderUserId Helper​

    The getFirstProviderUserId method returns the first user ID that it finds for the user. For example if the user has signed up with email, it will return the email. If the user has signed up with Google, it will return the Google ID.

    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
    const MainPage = ({ user }) => {
      const userId = user.getFirstProviderUserId()
      // ...
    }
    src/tasks.js
    export const createTask = async (args, context) => {
      const userId = context.user.getFirstProviderUserId()
      // ...
    }

    * Multiple identities per user will be possible in the future and then the getFirstProviderUserId method will return the ID of the first identity that it finds without any guarantees about which one it will be.

    Including the User with Other Entities​

    Sometimes, you might want to include the user's data when fetching other entities. For example, you might want to include the user's data with the tasks they have created.

    We'll mention the auth and the identities relations which we will explain in more detail later in the Entities Explained section.

    Be careful about sensitive data

    You'll need to include the auth and the identities relations to get the full auth data about the user. However, you should keep in mind that the providerData field in the identities can contain sensitive data like the user's hashed password (in case of email or username auth), so you will likely want to exclude it if you are returning those values to the client.

    You can include the full user's data with other entities using the include option in the Prisma queries:

    src/tasks.js
    export const getAllTasks = async (args, context) => {
      return context.entities.Task.findMany({
        orderBy: { id: 'desc' },
        select: {
          id: true,
          title: true,
          user: {
            include: {
              auth: {
                include: {
                  identities: {
                    // Including only the `providerName` and `providerUserId` fields
                    select: {
                      providerName: true,
                      providerUserId: true,
                    },
                  },
                },
              },
            },
          },
        },
      })
    }

    If you have some piece of the auth data that you want to access frequently (for example the username), it's best to store it at the top level of the User entity.

    For example, save the username or email as a property on the User and you'll be able to access it without including the auth and identities fields. We show an example in the Defining Extra Fields on the User Entity section of the docs.

    Getting Auth Data from the User Object​

    When you have the user object with the auth and identities fields, it can be a bit tedious to obtain the auth data (like username or Google ID) from it:

    src/MainPage.jsx
    function MainPage() {
      // ...
      return (
        <div className="tasks">
          {tasks.map((task) => (
            <div key={task.id} className="task">
              {task.title} by {task.user.auth?.identities[0].providerUserId}
            </div>
          ))}
        </div>
      )
    }

    Wasp offers a few helper methods to access the user's auth data when you retrieve the user like this. They are getUsername, getEmail and getFirstProviderUserId. They can be used both on the client and the server.

    getUsername​

    It accepts the user object and if the user signed up with the Username & password auth method, it returns the username or null otherwise. The user object needs to have the auth and the identities relations included.

    src/MainPage.jsx
    import { getUsername } from 'wasp/auth'

    function MainPage() {
      // ...
      return (
        <div className="tasks">
          {tasks.map((task) => (
            <div key={task.id} className="task">
              {task.title} by {getUsername(task.user)}
            </div>
          ))}
        </div>
      )
    }

    getEmail​

    It accepts the user object and if the user signed up with the Email auth method, it returns the email or null otherwise. The user object needs to have the auth and the identities relations included.

    src/MainPage.jsx
    import { getEmail } from 'wasp/auth'

    function MainPage() {
      // ...
      return (
        <div className="tasks">
          {tasks.map((task) => (
            <div key={task.id} className="task">
              {task.title} by {getEmail(task.user)}
            </div>
          ))}
        </div>
      )
    }

    getFirstProviderUserId​

    It returns the first user ID that it finds for the user. For example if the user has signed up with email, it will return the email. If the user has signed up with Google, it will return the Google ID. The user object needs to have the auth and the identities relations included.

    src/MainPage.jsx
    import { getFirstProviderUserId } from 'wasp/auth'

    function MainPage() {
      // ...
      return (
        <div className="tasks">
          {tasks.map((task) => (
            <div key={task.id} className="task">
              {task.title} by {getFirstProviderUserId(task.user)}
            </div>
          ))}
        </div>
      )
    }

    Entities Explained​

    To store user's auth information, Wasp does a few things behind the scenes. Wasp takes your schema.prisma file and combines it with additional entities to create the final schema.prisma file that is used in your app.

    In this section, we will explain which entities are created and how they are connected.

    User Entity​

    When you want to add authentication to your app, you need to specify the userEntity field.

    For example, you might set it to User:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.14.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        // ...
      },
    }

    And define the User in the schema.prisma file:

    schema.prisma
    model User {
      id Int @id @default(autoincrement())
      // Any other fields you want to store about the user
    }

    The User 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.

    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.

    model Auth {
      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[]
    }

    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.

    model AuthIdentity {
      providerName   String
      providerUserId String
      providerData   String @default("{}")
      authId         String
      auth           Auth   @relation(fields: [authId], references: [id], onDelete: Cascade)

      @@id([providerName, providerUserId])
    }

    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.

    model Session {
      id        String   @id @unique
      expiresAt DateTime
      userId    String
      auth      Auth     @relation(references: [id], fields: [userId], onDelete: Cascade)

      @@index([userId])
    }

    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.

    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.14.0/auth/overview.html b/docs/0.14.0/auth/overview.html index db7278f1dc..c496eda9bb 100644 --- a/docs/0.14.0/auth/overview.html +++ b/docs/0.14.0/auth/overview.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.14.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

    Discord »

    Users sign in with their Discord 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. In addition to that, it will also contain all the auth-related fields that Wasp stores. This includes things like the username or the email verification status. For example, if you have a user that signed up using an email and password, the user object might look like this:

    const user = {
      // User data
      id: "cluqsex9500017cn7i2hwsg17",
      address: "Some address",

      // Auth methods specific data
      identities: {
        email: {
          id: "user@app.com",
          isEmailVerified: true,
          emailVerificationSentAt: "2024-04-08T10:06:02.204Z",
          passwordResetSentAt: null,
        },
      },
    }

    You can read more about how the User is connected to the rest of the auth system and how you can access the user data in the Accessing User Data 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",
      },
    }
    schema.prisma
    model User {
      id      Int     @id @default(autoincrement())
      address String?
    }

    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 you defined in the schema.prisma file.

    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",
      }
    }

    //...

    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 is connected to the rest of the auth system and how you can access the user data in the Accessing User Data 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

    Discord »

    Users sign in with their Discord 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 essential 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 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.14.0/auth/social-auth/discord.html b/docs/0.14.0/auth/social-auth/discord.html index c282fa895d..9e28aa46a0 100644 --- a/docs/0.14.0/auth/social-auth/discord.html +++ b/docs/0.14.0/auth/social-auth/discord.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.14.0

    Discord

    Wasp supports Discord Authentication out of the box.

    Letting your users log in using their Discord accounts turns the signup process into a breeze.

    Let's walk through enabling Discord Authentication, explain some of the default settings, and show how to override them.

    Setting up Discord Auth​

    Enabling Discord Authentication comes down to a series of steps:

    1. Enabling Discord authentication in the Wasp file.
    2. Adding the User entity.
    3. Creating a Discord 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 routes and pages
    route LoginRoute { ... }
    page LoginPage { ... }

    1. Adding Discord Auth to Your Wasp File​

    Let's start by properly configuring the Auth object:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.14.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the User entity  (we'll define it next)
        userEntity: User,
        methods: {
          // 2. Enable Discord Auth
          discord: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    2. Add the User Entity​

    Let's now define the app.auth.userEntity entity in the schema.prisma file:

    schema.prisma
    // 3. Define the user entity
    model User {
      id Int @id @default(autoincrement())
      // Add your own fields below
      // ...
    }

    3. Creating a Discord App​

    To use Discord as an authentication method, you'll first need to create a Discord App and provide Wasp with your client key and secret. Here's how you do it:

    1. Log into your Discord account and navigate to: https://discord.com/developers/applications.
    2. Select New Application.
    3. Supply required information.
    Discord Applications Screenshot
    1. Go to the OAuth2 tab on the sidebar and click Add Redirect
    • For development, put: http://localhost:3001/auth/discord/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/discord/callback.
    1. Hit Save Changes.
    2. Hit Reset Secret.
    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
    DISCORD_CLIENT_ID=your-discord-client-id
    DISCORD_CLIENT_SECRET=your-discord-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
    // ...

    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 Discord Auth! 🎉

    Discord 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 discord: {} to the auth.methods dictionary to use it with default settings.

    main.wasp
    app myApp {
      wasp: {
        version: "^0.14.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          discord: {}
        },
        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 Discord​

    We are using Discord's API and its /users/@me endpoint to get the user data.

    The data we receive from Discord on the /users/@me endpoint looks something like this:

    {
      "id": "80351110224678912",
      "username": "Nelly",
      "discriminator": "1337",
      "avatar": "8342729096ea3675442027381ff50dfe",
      "verified": true,
      "flags": 64,
      "banner": "06c16474723fe537c283b8efa61a30c8",
      "accent_color": 16711680,
      "premium_type": 1,
      "public_flags": 64,
      "avatar_decoration_data": {
        "sku_id": "1144058844004233369",
        "asset": "a_fed43ab12698df65902ba06727e20c0e"
      }
    }

    The fields you receive will depend on the scopes you requested. The default scope is set to identify only. If you want to get the email, you need to specify the email scope in the configFn function.

    For an up to date info about the data received from Discord, please refer to the Discord API documentation.

    Using the Data Received From Discord​

    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.14.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          discord: {
            configFn: import { getConfig } from "@src/auth/discord.js",
            userSignupFields: import { userSignupFields } from "@src/auth/discord.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }
    schema.prisma
    model User {
      id          Int    @id @default(autoincrement())
      username    String @unique
      displayName String
    }

    // ...
    src/auth/discord.js
    export const userSignupFields = {
      username: (data) => data.profile.global_name,
      avatarUrl: (data) => data.profile.avatar,
    };

    export function getConfig() {
      return {
        scopes: ['identify'],
      };
    }

    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.

    When you receive the user object on the client or the server, you'll be able to access the user's Discord ID like this:

    const discordIdentity = user.identities.discord

    // Discord User ID for example "80351110224678912"
    discordIdentity.id

    Read more about accessing the user data in the Accessing User Data section of the docs.

    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.14.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          discord: {
            configFn: import { getConfig } from "@src/auth/discord.js",
            userSignupFields: import { userSignupFields } from "@src/auth/discord.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    The discord dict has the following properties:

    • configFn: ExtImport​

      This function should return an object with the scopes for the OAuth provider.

      src/auth/discord.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/0.14.0/auth/social-auth/github.html b/docs/0.14.0/auth/social-auth/github.html index 5545c5409b..da1b514638 100644 --- a/docs/0.14.0/auth/social-auth/github.html +++ b/docs/0.14.0/auth/social-auth/github.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ 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 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.14.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 in the schema.prisma file:

    schema.prisma
    // 3. Define the user entity
    model User {
      id Int @id @default(autoincrement())
      // Add your own fields below
      // ...
    }

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

    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.14.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.14.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"
      },
    }
    schema.prisma
    model User {
      id          Int    @id @default(autoincrement())
      username    String @unique
      displayName String
    }

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

    When you receive the user object on the client or the server, you'll be able to access the user's GitHub ID like this:

    const githubIdentity = user.identities.github

    // GitHub User ID for example "12345678"
    githubIdentity.id

    Read more about accessing the user data in the Accessing User Data section of the docs.

    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.14.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/0.14.0/auth/social-auth/google.html b/docs/0.14.0/auth/social-auth/google.html index 6979965f65..631189d212 100644 --- a/docs/0.14.0/auth/social-auth/google.html +++ b/docs/0.14.0/auth/social-auth/google.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ 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.14.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.14.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"
      },
    }
    schema.prisma
    model User {
      id          Int    @id @default(autoincrement())
      username    String @unique
      displayName String
    }

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

    When you receive the user object on the client or the server, you'll be able to access the user's Google ID like this:

    const googleIdentity = user.identities.google

    // Google User ID for example "123456789012345678901"
    googleIdentity.id

    Read more about accessing the user data in the Accessing User Data section of the docs.

    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.14.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/0.14.0/auth/social-auth/keycloak.html b/docs/0.14.0/auth/social-auth/keycloak.html index 9ea4547b6e..463372b2ae 100644 --- a/docs/0.14.0/auth/social-auth/keycloak.html +++ b/docs/0.14.0/auth/social-auth/keycloak.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ 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.14.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.14.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"
      },
    }
    schema.prisma
    model User {
      id          Int    @id @default(autoincrement())
      username    String @unique
      displayName String
    }

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

    When you receive the user object on the client or the server, you'll be able to access the user's Keycloak ID like this:

    const keycloakIdentity = user.identities.keycloak

    // Keycloak User ID for example "12345678-1234-1234-1234-123456789012"
    keycloakIdentity.id

    Read more about accessing the user data in the Accessing User Data section of the docs.

    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.14.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/0.14.0/auth/social-auth/overview.html b/docs/0.14.0/auth/social-auth/overview.html index 0e448f1243..bebb9261ad 100644 --- a/docs/0.14.0/auth/social-auth/overview.html +++ b/docs/0.14.0/auth/social-auth/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -31,7 +31,7 @@ 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.14.0/auth/ui.html b/docs/0.14.0/auth/ui.html index ca8ad9a9a8..54e8c08362 100644 --- a/docs/0.14.0/auth/ui.html +++ b/docs/0.14.0/auth/ui.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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, Keycloak, and Discord 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, Keycloak, and Discord 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.14.0/auth/username-and-pass.html b/docs/0.14.0/auth/username-and-pass.html index 42e753a374..b15521cd65 100644 --- a/docs/0.14.0/auth/username-and-pass.html +++ b/docs/0.14.0/auth/username-and-pass.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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 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.14.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:

    schema.prisma
    // 3. Define the user entity
    model User {
      id Int @id @default(autoincrement())
      // Add your own fields below
      // ...
    }

    You can read more about how the User is connected to the rest of the auth system and how you can access the user data in the Accessing User Data 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
    // ...
    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.

    When you receive the user object on the client or the server, you'll be able to access the user's username like this:

    const usernameIdentity = user.identities.username

    // Username that the user used to sign up, e.g. "fluffyllama"
    usernameIdentity.id

    Read more about accessing the user data in the Accessing User Data section of the docs.

    API Reference​

    userEntity fields​

    main.wasp
    app myApp {
      wasp: {
        version: "^0.14.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login"
      }
    }
    schema.prisma
    model User {
      id Int @id @default(autoincrement())
    }

    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.14.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.14.0/contact.html b/docs/0.14.0/contact.html index 068aeb8488..cc30aa5a2c 100644 --- a/docs/0.14.0/contact.html +++ b/docs/0.14.0/contact.html @@ -18,14 +18,14 @@ - - - + + +
    - - + + \ No newline at end of file diff --git a/docs/0.14.0/contributing.html b/docs/0.14.0/contributing.html index 8e9ed424bd..8369fbd6b9 100644 --- a/docs/0.14.0/contributing.html +++ b/docs/0.14.0/contributing.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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.14.0/data-model/backends.html b/docs/0.14.0/data-model/backends.html index c1d565d1bf..a163b1a3d6 100644 --- a/docs/0.14.0/data-model/backends.html +++ b/docs/0.14.0/data-model/backends.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -34,7 +34,7 @@ Wasp defines DbSeedFn like this:

    type DbSeedFn = (prisma: PrismaClient) => Promise<void>

    Annotating the function devSeedSimple with this type tells TypeScript:

    • The seeding function's argument (prisma) is of type PrismaClient.
    • The seeding function's return value is Promise<void>.

    Running seed functions​

    Run the command wasp db seed and Wasp will ask you which seed function you'd like to run (if you've defined more than one).

    Alternatively, run the command wasp db seed <seed-name> to choose a specific seed function right away, for example:

    wasp db seed devSeedSimple

    Check the API Reference for more details on these commands.

    tip

    You'll often want to call wasp db seed right after you run wasp db reset, as it makes sense to fill the database with initial data after clearing it.

    API Reference​

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      db: {
        seeds: [
          import devSeed from "@src/dbSeeds.js"
        ],
      }
    }

    app.db is a dictionary with the following fields (all fields are optional):

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

    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.14.0/data-model/crud.html b/docs/0.14.0/data-model/crud.html index 6492a204eb..02ded8e01d 100644 --- a/docs/0.14.0/data-model/crud.html +++ b/docs/0.14.0/data-model/crud.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ Read more about the default implementations here.

    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,
            },
          },
        },
      })
    }

    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 works on top of an 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.14.0/data-model/entities.html b/docs/0.14.0/data-model/entities.html index de24743809..4b859dc037 100644 --- a/docs/0.14.0/data-model/entities.html +++ b/docs/0.14.0/data-model/entities.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.14.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. This means that you use the schema.prisma file to define your database models and relationships. Wasp understands the Prisma schema file and picks up all the models you define there. You can read more about this in the Prisma Schema File section of the docs.

    In your project, you'll find a schema.prisma file in the root directory:

    .
    ├── main.wasp
    ...
    ├── schema.prisma
    ├── src
    ├── tsconfig.json
    └── vite.config.ts

    Prisma uses the Prisma Schema Language, a simple definition language explicitly created for defining models. 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​

    A Prisma model declaration in the schema.prisma file represents a Wasp Entity.

    Entity vs Model

    You might wonder why we distinguish between a Wasp Entity and a Prisma model if they're essentially the same thing right now.

    While defining a Prisma model is currently the only way to create an Entity in Wasp, the Entity concept is a higher-level abstraction. We plan to expand on Entities in the future, both in terms of how you can define them and what you can do with them.

    So, think of an Entity as a Wasp concept and a model as a Prisma concept. For now, all Prisma models are Entities and vice versa, but this relationship might evolve as Wasp grows.

    Here's how you could define an Entity that represents a Task:

    schema.prisma
    model Task {
      id          String  @id @default(uuid())
      description String
      isDone      Boolean @default(false)
    }

    The above Prisma model 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 - A string value serving as a primary key. The database automatically generates it by generating a random unique 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 the schema.prisma file.
    2. Run wasp db migrate-dev. This command syncs the database model with the Entity definitions the schema.prisma 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.14.0/data-model/operations/actions.html b/docs/0.14.0/data-model/operations/actions.html index d004cf814d..01c7904bb4 100644 --- a/docs/0.14.0/data-model/operations/actions.html +++ b/docs/0.14.0/data-model/operations/actions.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -47,7 +47,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 (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 (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 (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.14.0/data-model/operations/overview.html b/docs/0.14.0/data-model/operations/overview.html index f74e3ac882..136eed2be3 100644 --- a/docs/0.14.0/data-model/operations/overview.html +++ b/docs/0.14.0/data-model/operations/overview.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.14.0

    Overview

    While Entities enable you to 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, Queries are meant for reading data, and Actions are meant for changing it (either by updating existing entries or creating new ones).

    Keep reading to find out all there is to know about Operations in Wasp.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/data-model/operations/queries.html b/docs/0.14.0/data-model/operations/queries.html index 012c1c3dd0..1a68e167e4 100644 --- a/docs/0.14.0/data-model/operations/queries.html +++ b/docs/0.14.0/data-model/operations/queries.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -50,7 +50,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.14.0/data-model/prisma-file.html b/docs/0.14.0/data-model/prisma-file.html index bc693cd353..37f20e9c70 100644 --- a/docs/0.14.0/data-model/prisma-file.html +++ b/docs/0.14.0/data-model/prisma-file.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.0

    Prisma Schema File

    Wasp uses Prisma to interact with the database. Prisma is a "Next-generation Node.js and TypeScript ORM" that provides a type-safe API for working with your database.

    With Prisma, you define your application's data model in a schema.prisma file. Read more about how Wasp Entities relate to Prisma models on the Entities page.

    In Wasp, the schema.prisma file is located in your project's root directory:

    .
    ├── main.wasp
    ...
    ├── schema.prisma
    ├── src
    ├── tsconfig.json
    └── vite.config.ts

    Wasp uses the schema.prisma file to understand your app's data model and generate the necessary code to interact with the database.

    Wasp file and Prisma schema file​

    Let's see how Wasp and Prisma files work together to define your application.

    Here's an example schema.prisma file where we defined some database options and two models (User and Task) with a one-to-many relationship:

    schema.prisma
    datasource db {
      provider = "postgresql"
      url      = env("DATABASE_URL")
    }

    generator client {
      provider = "prisma-client-js"
    }

    model User {
      id      Int        @id @default(autoincrement())
      tasks   Task[]
    }

    model Task {
      id          Int        @id @default(autoincrement())
      description String
      isDone      Boolean    @default(false)
      user        User       @relation(fields: [userId], references: [id])
      userId      Int
    }

    Wasp reads this schema.prisma file and extracts the info about your database models and database config.

    The datasource block defines which database you want to use (PostgreSQL in this case) and some other options.

    The generator block defines how to generate the Prisma Client code that you can use in your application to interact with the database.

    Relationship between Wasp file and Prisma file
    Relationship between Wasp file and Prisma file

    Finally, Prisma models become Wasp Entities which can be then used in the main.wasp file:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.14.0"
      },
      title: "My App",
    }

    ...

    // Using Wasp Entities in the Wasp file

    query getTasks {
      fn: import { getTasks } from "@src/queries",
      entities: [Task]
    }

    job myJob {
      executor: PgBoss,
      perform: {
        fn: import { foo } from "@src/workers/bar"
      },
      entities: [Task],
    }

    api fooBar {
      fn: import { fooBar } from "@src/apis",
      entities: [Task],
      httpRoute: (GET, "/foo/bar/:email")
    }

    In the implementation of the getTasks query, Task is a Wasp Entity that corresponds to the Task model defined in the schema.prisma file.

    The same goes for the myJob job and fooBar API, where Task is used as an Entity.

    To learn more about the relationship between Wasp Entities and Prisma models, check out the Entities page.

    Wasp-specific Prisma configuration​

    Wasp mostly lets you use the Prisma schema file as you would in any other JS/TS project. However, there are some Wasp-specific rules you need to follow.

    The datasource block​

    schema.prisma
    datasource db {
      provider = "postgresql"
      url      = env("DATABASE_URL")
    }

    Wasp takes the datasource you write and use it as-is.

    There are some rules you need to follow:

    • You can only use "postgresql" or "sqlite" as the provider because Wasp only supports PostgreSQL and SQLite databases for now.
    • You must set the url field to env("DATABASE_URL") so that Wasp can work properly with your database.

    The generator blocks​

    schema.prisma
    generator client {
      provider = "prisma-client-js"
    }

    Wasp requires that there is a generator block with provider = "prisma-client-js" in the schema.prisma file.

    You can add additional generators if you need them in your project.

    The model blocks​

    schema.prisma
    model User {
      id      Int        @id @default(autoincrement())
      tasks   Task[]
    }

    model Task {
      id          Int        @id @default(autoincrement())
      description String
      isDone      Boolean    @default(false)
      user        User       @relation(fields: [userId], references: [id])
      userId      Int
    }

    You can define your models in any way you like, if it's valid Prisma schema code, it will work with Wasp.

    Triple slash comments

    Wasp doesn't yet fully support /// comment syntax in the schema.prisma file. We are tracking it here, let us know if this is something you need.

    Prisma preview features​

    Prisma is still in active development and some of its features are not yet stable. To enable various preview features in Prisma, you need to add the previewFeatures field to the generator block in the schema.prisma file.

    For example, one useful Prisma preview feature is PostgreSQL extensions support, which allows you to use PostgreSQL extensions like pg_vector or pg_trgm in your database schema:

    schema.prisma
    datasource db {
      provider   = "postgresql"
      url        = env("DATABASE_URL")
      extensions = [pgvector(map: "vector")]
    }

    generator client {
      provider        = "prisma-client-js"
      previewFeatures = ["postgresqlExtensions"]
    }

    // ...

    Read more about preview features in the Prisma docs here or about using PostgreSQL extensions here.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/editor-setup.html b/docs/0.14.0/editor-setup.html index e9f170596a..42c06ebc7e 100644 --- a/docs/0.14.0/editor-setup.html +++ b/docs/0.14.0/editor-setup.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.14.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
    • the Prisma extension for .prisma files
    • scaffolding of new project files
    • code completion
    • diagnostics (errors and warnings)
    • go to definition

    and more!

    LSP Problems

    If you are using TypeScript, your editor may sometimes report type and import errors even while wasp start is running.

    This happens when the TypeScript Language Server gets out of sync with the current code. If you're using VS Code, you can manually restart the language server by opening the command palette and selecting "TypeScript: Restart TS Server." Open the command pallete with:

    • Ctrl + Shift + P if you're on Windows or Linux.
    • Cmd + Shift + P if you're on a Mac.
    - - + + \ No newline at end of file diff --git a/docs/0.14.0/general/cli.html b/docs/0.14.0/general/cli.html index 777438c7f3..67b7b65c4a 100644 --- a/docs/0.14.0/general/cli.html +++ b/docs/0.14.0/general/cli.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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.

    using prisma CLI directly

    Although Wasp uses the schema.prisma file to define the database schema, you must not use the prisma command directly. Instead, use the wasp db commands.

    Wasp adds some additional functionality on top of Prisma, and using prisma commands directly can lead to unexpected behavior e.g. missing auth models, incorrect database setup, etc.

    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.14.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.14.0/general/language.html b/docs/0.14.0/general/language.html index 212d8e8386..1d7661bae8 100644 --- a/docs/0.14.0/general/language.html +++ b/docs/0.14.0/general/language.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.14.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=})
      • 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
        • job
        • page
        • query
        • route
        • crud
      • Enum types
        • DbSystem
        • HttpMethod
        • JobExecutor
        • EmailProvider
      • Models from the schema.prisma file
        • You can reference models defined in the schema.prisma file in your Wasp file by using the model name e.g. Task.

    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.14.0/general/typescript.html b/docs/0.14.0/general/typescript.html index 3c6d40420c..4ea422a004 100644 --- a/docs/0.14.0/general/typescript.html +++ b/docs/0.14.0/general/typescript.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -33,7 +33,7 @@ support when implementing the Query. Thanks to this type, the compiler knows:

    • The type of the context object.
    • The type of args.
    • The Query's return type.

    And gives you Intellisense and type-checking. Read more about this feature here.

    You don't need to change anything inside the .wasp file.

    Migrating the rest of the project​

    You can migrate your project gradually - on a file-by-file basis.

    When you want to migrate a file, follow the procedure outlined above:

    1. Change the file's extension.
    2. Fix the type errors.
    3. Read the Wasp docs and decide which TypeScript features you want to use.
    LSP Problems

    If you are using TypeScript, your editor may sometimes report type and import errors even while wasp start is running.

    This happens when the TypeScript Language Server gets out of sync with the current code. If you're using VS Code, you can manually restart the language server by opening the command palette and selecting "TypeScript: Restart TS Server." Open the command pallete with:

    • Ctrl + Shift + P if you're on Windows or Linux.
    • Cmd + Shift + P if you're on a Mac.
    - - + + \ No newline at end of file diff --git a/docs/0.14.0/migrate-from-0-11-to-0-12.html b/docs/0.14.0/migrate-from-0-11-to-0-12.html index 9ae816813c..e7ed44690a 100644 --- a/docs/0.14.0/migrate-from-0-11-to-0-12.html +++ b/docs/0.14.0/migrate-from-0-11-to-0-12.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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.14.0/migrate-from-0-12-to-0-13.html b/docs/0.14.0/migrate-from-0-12-to-0-13.html index 8ad2140d46..8728a22698 100644 --- a/docs/0.14.0/migrate-from-0-12-to-0-13.html +++ b/docs/0.14.0/migrate-from-0-12-to-0-13.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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.

    Make sure to read the migration guide from 0.13.X to 0.14.X after you finish this one.

    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/0.14.0/migrate-from-0-13-to-0-14.html b/docs/0.14.0/migrate-from-0-13-to-0-14.html index 568b3eb0ef..dd94d54572 100644 --- a/docs/0.14.0/migrate-from-0-13-to-0-14.html +++ b/docs/0.14.0/migrate-from-0-13-to-0-14.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -30,7 +30,7 @@ below.

    If you have made changes to your tsconfig.json file, we recommend taking the new version of the file and reapplying them.

    Here's the new version of the tsconfig.json file:

    tsconfig.json
    // =============================== IMPORTANT =================================
    //
    // This file is only used for Wasp IDE support. You can change it to configure
    // your IDE checks, but none of these options will affect the TypeScript
    // compiler. Proper TS compiler configuration in Wasp is coming soon :)
    {
      "compilerOptions": {
        "module": "esnext",
        "target": "esnext",
        // We're bundling all code in the end so this is the most appropriate option,
        // it's also important for autocomplete to work properly.
        "moduleResolution": "bundler",
        // JSX support
        "jsx": "preserve",
        "strict": true,
        // Allow default imports.
        "esModuleInterop": true,
        "lib": ["dom", "dom.iterable", "esnext"],
        "allowJs": true,
        "typeRoots": [
          // This is needed to properly support Vitest testing with jest-dom matchers.
          // Types for jest-dom are not recognized automatically and Typescript complains
          // about missing types e.g. when using `toBeInTheDocument` and other matchers.
          "node_modules/@testing-library",
          // Specifying type roots overrides the default behavior of looking at the
          // node_modules/@types folder so we had to list it explicitly.
          // Source 1: https://www.typescriptlang.org/tsconfig#typeRoots
          // Source 2: https://github.com/testing-library/jest-dom/issues/546#issuecomment-1889884843
          "node_modules/@types"
        ],
        // Since this TS config is used only for IDE support and not for
        // compilation, the following directory doesn't exist. We need to specify
        // it to prevent this error:
        // https://stackoverflow.com/questions/42609768/typescript-error-cannot-write-file-because-it-would-overwrite-input-file
        "outDir": ".wasp/phantom"
      }
    }

    Migrate to the new schema.prisma file​

    To use the new schema.prisma file, you need to move your entities from the .wasp file to the schema.prisma file.

    1. Create a new schema.prisma file

    Create a new file named schema.prisma in the root of your project:

    .
    ├── main.wasp
    ...
    ├── schema.prisma
    ├── src
    ├── tsconfig.json
    └── vite.config.ts

    2. Add the datasource block to the schema.prisma file

    This block specifies the database type and connection URL:

    schema.prisma
    datasource db {
      provider = "sqlite"
      url      = env("DATABASE_URL")
    }

    • The provider should be either "postgresql" or "sqlite".

    • The url must be set to env("DATABASE_URL") so that Wasp can inject the database URL from the environment variables.

    3. Add the generator block to the schema.prisma file

    This block specifies the Prisma Client generator Wasp uses:

    schema.prisma
    datasource db {
      provider = "sqlite"
      url      = env("DATABASE_URL")
    }

    generator client {
      provider = "prisma-client-js"
    }
    • The provider should be set to "prisma-client-js".

    4. Move your entities to the schema.prisma file

    Move the entities from the .wasp file to the schema.prisma file:

    schema.prisma
    datasource db {
      provider = "sqlite"
      url      = env("DATABASE_URL")
    }

    generator client {
      provider = "prisma-client-js"
    }

    // There are some example entities, you should move your entities here
    model User {
      id       Int @id @default(autoincrement())
      tasks    Task[]
    }

    model Task {
      id          Int @id @default(autoincrement())
      description String
      isDone      Boolean
      userId      Int
      user        User @relation(fields: [userId], references: [id])
    }

    When moving the entities over, you'll need to change entity to model and remove the =psl and psl= tags.

    If you had the following in the .wasp file:

    main.wasp
    entity Task {=psl
      // Stays the same
    psl=}

    ... it would look like this in the schema.prisma file:

    schema.prisma
    model Task {
      // Stays the same
    }

    5. Remove app.db.system field from the Wasp file

    We now configure the DB system in the schema.prisma file, so there is no need for that field in the Wasp file.

    main.wasp
    app MyApp {
      // ...
      db: {
        system: PostgreSQL,
      }
    }

    6. Migrate Prisma preview features config to the schema.prisma file

    If you didn't use any Prisma preview features, you can skip this step.

    If you had the following in the .wasp file:

    main.wasp
    app MyApp {
      // ...
      db: {
        prisma: {
          clientPreviewFeatures: ["postgresqlExtensions"]
          dbExtensions: [
            { name: "hstore", schema: "myHstoreSchema" },
            { name: "pg_trgm" },
            { name: "postgis", version: "2.1" },
          ]
        }
      }
    }

    ... it will become this:

    schema.prisma
    datasource db {
      provider = "postgresql"
      url      = env("DATABASE_URL")
      extensions = [hstore(schema: "myHstoreSchema"), pg_trgm, postgis(version: "2.1")]
    }

    generator client {
      provider = "prisma-client-js"
      previewFeatures = ["postgresqlExtensions"]
    }

    All that's left to do is migrate the database.

    To avoid type errors, it's best to take care of database migrations after you've migrated the rest of the code. So, just keep reading, and we will remind you to migrate the database as the last step of the migration guide.

    Read more about the Prisma Schema File and how Wasp uses it to generate the database schema and Prisma client.

    Migrate how you access user auth fields​

    We had to make a couple of breaking changes to reach the new simpler API.

    Follow the steps below to migrate:

    1. Replace the getUsername helper with user.identities.username.id

      If you didn't use the getUsername helper in your code, you can skip this step.

      This helper changed and it no longer works with the user you receive as a prop on a page or through the context. You'll need to replace it with user.identities.username.id.

      src/MainPage.tsx
      import { getUsername, AuthUser } from 'wasp/auth'

      const MainPage = ({ user }: { user: AuthUser }) => {
        const username = getUsername(user)
        // ...
      }
      src/tasks.ts
      import { getUsername } from 'wasp/auth'

      export const createTask: CreateTask<...>  = async (args, context) => {
          const username = getUsername(context.user)
          // ...
      }

    2. Replace the getEmail helper with user.identities.email.id

      If you didn't use the getEmail helper in your code, you can skip this step.

      This helper changed and it no longer works with the user you receive as a prop on a page or through the context. You'll need to replace it with user.identities.email.id.

      src/MainPage.tsx
      import { getEmail, AuthUser } from 'wasp/auth'

      const MainPage = ({ user }: { user: AuthUser }) => {
        const email = getEmail(user)
        // ...
      }
      src/tasks.ts
      import { getEmail } from 'wasp/auth'

      export const createTask: CreateTask<...>  = async (args, context) => {
          const email = getEmail(context.user)
          // ...
      }

    3. Replace accessing providerData with user.identities.<provider>.<value>

      If you didn't use any data from the providerData object, you can skip this step.

      Replace <provider> with the provider name (for example username, email, google, github, etc.) and <value> with the field you want to access (for example isEmailVerified).

      src/MainPage.tsx
      import { findUserIdentity, AuthUser } from 'wasp/auth'

      function getProviderData(user: AuthUser) {
        const emailIdentity = findUserIdentity(user, 'email')
        // We needed this before check for proper type support
        return emailIdentity && 'isEmailVerified' in emailIdentity.providerData
          ? emailIdentity.providerData
          : null
      }

      const MainPage = ({ user }: { user: AuthUser }) => {
        const providerData = getProviderData(user)
        const isEmailVerified = providerData ? providerData.isEmailVerified : null
        // ...
      }

    4. Use getFirstProviderUserId directly on the user object

      If you didn't use getFirstProviderUserId in your code, you can skip this step.

      You should replace getFirstProviderUserId(user) with user.getFirstProviderUserId().

      src/MainPage.tsx
      import { getFirstProviderUserId, AuthUser } from 'wasp/auth'

      const MainPage = ({ user }: { user: AuthUser }) => {
        const userId = getFirstProviderUserId(user)
        // ...
      }
      src/tasks.ts
      import { getFirstProviderUserId } from 'wasp/auth'

      export const createTask: CreateTask<...>  = async (args, context) => {
          const userId = getFirstProviderUserId(context.user)
          // ...
      }

    5. Replace findUserIdentity with checks on user.identities.<provider>

      If you didn't use findUserIdentity in your code, you can skip this step.

      Instead of using findUserIdentity to get the identity object, you can directly check if the identity exists on the identities object.

      src/MainPage.tsx
      import { findUserIdentity, AuthUser } from 'wasp/auth'

      const MainPage = ({ user }: { user: AuthUser }) => {
        const usernameIdentity = findUserIdentity(user, 'username')
        if (usernameIdentity) {
          // ...
        }
      }
      src/tasks.ts
      import { findUserIdentity } from 'wasp/auth'

      export const createTask: CreateTask<...>  = async (args, context) => {
          const usernameIdentity = findUserIdentity(context.user, 'username')
          if (usernameIdentity) {
              // ...
          }
      }

    Migrate the database​

    Finally, you can Run the Wasp CLI to regenerate the new Prisma client:

    wasp db migrate-dev

    This command generates the Prisma client based on the schema.prisma file.

    Read more about the Prisma Schema File and how Wasp uses it to generate the database schema and Prisma client.

    That's it!

    You should now be able to run your app with the new Wasp 0.14.0. We recommend reading through the updated Accessing User Data section to get a better understanding of the new API.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/project/client-config.html b/docs/0.14.0/project/client-config.html index fd4c2e2336..7b21bfd9af 100644 --- a/docs/0.14.0/project/client-config.html +++ b/docs/0.14.0/project/client-config.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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.14.0/project/css-frameworks.html b/docs/0.14.0/project/css-frameworks.html index e3ba20a2c8..6a6c62deca 100644 --- a/docs/0.14.0/project/css-frameworks.html +++ b/docs/0.14.0/project/css-frameworks.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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.14.0/project/custom-vite-config.html b/docs/0.14.0/project/custom-vite-config.html index 24886c55eb..ea0b1f0787 100644 --- a/docs/0.14.0/project/custom-vite-config.html +++ b/docs/0.14.0/project/custom-vite-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.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.14.0/project/customizing-app.html b/docs/0.14.0/project/customizing-app.html index 8e6b259cfa..ca5e9551de 100644 --- a/docs/0.14.0/project/customizing-app.html +++ b/docs/0.14.0/project/customizing-app.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.14.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.14.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.14.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.14.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.14.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:

    • wasp: dict required Wasp compiler configuration. It is a dictionary with a single field:

      • version: string required

        The version specifies which versions of Wasp are compatible with the app. It should contain a valid SemVer range

        info

        For now, the version field only supports caret ranges (i.e., ^x.y.z). Support for the full specification will come in a future version of Wasp

    • title: string required

      Title of your app. It will appear in the browser tab, next to the favicon.

    • head: [string]

      List of additional lines (e.g. <link> or <script> tags) to be included in the <head> of your HTML document.

    The rest of the fields are covered in dedicated sections of the docs:

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/project/dependencies.html b/docs/0.14.0/project/dependencies.html index 33f8c5f03e..7cbbcf9bdd 100644 --- a/docs/0.14.0/project/dependencies.html +++ b/docs/0.14.0/project/dependencies.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.14.0

    Dependencies

    In a Wasp project, dependencies are defined in a standard way for JavaScript projects: using the package.json file, located at the root of your project. You can list your dependencies under the dependencies or devDependencies fields.

    Adding a New Dependency​

    To add a new package, like date-fns (a great date handling library), you use npm:

    npm install date-fns

    This command will add the package in the dependencies section of your package.json file.

    You will notice that there are some other packages in the dependencies section, like react and wasp. These are the packages that Wasp uses internally, and you should not modify or remove them.

    Using Packages that are Already Used by Wasp Internally​

    In the current version of Wasp, if Wasp is already internally using a certain dependency (e.g. React) with a certain version specified, you are not allowed to define that same npm dependency yourself while specifying a different version.

    If you do that, you will get an error message telling you which exact version you have to use for that dependency. This means Wasp dictates exact versions of certain packages, so for example you can't choose the version of React you want to use.

    note

    We are currently working on a restructuring that will solve this and some other quirks: check issue #734 to follow our progress.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/project/env-vars.html b/docs/0.14.0/project/env-vars.html index 1729a78bb6..5fd625869b 100644 --- a/docs/0.14.0/project/env-vars.html +++ b/docs/0.14.0/project/env-vars.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ By default, in the .gitignore file that comes with a new Wasp app, we ignore all dotenv files.

    Dotenv files

    dotenv files are a popular method for storing configuration: to learn more about them in general, check out the dotenv npm package.

    2. Using Shell​

    If you set environment variables in the shell where you run your Wasp commands (e.g., wasp start), Wasp will recognize them.

    You can set environment variables in the .profile or a similar file, which will set them permanently, or you can set them temporarily by defining them at the start of a command (SOME_VAR_NAME=SOMEVALUE wasp start).

    This is not specific to Wasp and is simply how environment variables can be set in the shell.

    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 during development, you should use .env files instead. However, it can be useful for occasionally overriding specific environment variables because environment variables set this way take precedence over those defined in .env files.

    Defining Env Vars in Production​

    While in development, we had the option of using .env.client and .env.server files which made it easy to define and manage env vars. However, for production, .env.client and .env.server files will be ignored, and we need to provide env vars differently.

    Env vars usage in development and production

    Client Env Vars​

    Client env vars are embedded into the client code during the build process, making them public and readable by anyone. Therefore, you should never store secrets in them (such as secret API keys).

    When building for production .env.client will be ignored, since it is meant to be used only during development. Instead, you should provide the production client env vars directly to the build command that turns client code into static files:

    REACT_APP_SOME_VAR_NAME=somevalue REACT_APP_SOME_OTHER_VAR_NAME=someothervalue npm run build

    Check the deployment docs for more details.

    Also, notice that you can't and shouldn't provide env vars to the client code by setting them on the hosting provider where you deployed them (unlike server env vars, where this is how you should do it). Your client code will ignore those, as at that point client code is just static files.

    How it works

    What happens behind the scenes is that Wasp will replace all occurrences of import.meta.env.REACT_APP_SOME_VAR_NAME in your client code with the env var value you provided. This is done during the build process, so the value is embedded into the static files produced from the client code.

    Read more about it in Vite's docs.

    Server Env Vars​

    When building for production .env.server will be ignored, since it is meant to be used only during development.

    You can provide production env vars to your server code in production by defining them and making them available on the server where your server code is running.

    Setting this up will highly depend on where you are deploying your Wasp project, but in general it comes down to defining the env vars via mechanisms that your hosting provider provides.

    For example, if you deploy your project to Fly, you can define them using the flyctl CLI tool:

    flyctl secrets set SOME_VAR_NAME=somevalue

    You can read a lot more details in the deployment section of the docs. We go into detail on how to define env vars for each deployment option.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/project/server-config.html b/docs/0.14.0/project/server-config.html index b0fd406a85..4114f30bd9 100644 --- a/docs/0.14.0/project/server-config.html +++ b/docs/0.14.0/project/server-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.0

    Server Config

    You can configure the behavior of the server via the server field of app declaration:

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      server: {
        setupFn: import { mySetupFunction } from "@src/myServerSetupCode.js",
        middlewareConfigFn: import { myMiddlewareConfigFn } from "@src/myServerSetupCode.js"
      }
    }

    Setup Function​

    Adding a Custom Route​

    As an example, adding a custom route would look something like:

    src/myServerSetupCode.ts
    export const mySetupFunction = async ({ app }) => {
      addCustomRoute(app)
    }

    function addCustomRoute(app) {
      app.get('/customRoute', (_req, res) => {
        res.send('I am a custom route')
      })
    }

    Storing Some Values for Later Use​

    In case you want to store some values for later use, or to be accessed by the Operations you do that in the setupFn function.

    Dummy example of such function and its usage:

    src/myServerSetupCode.js
    let someResource = undefined

    export const mySetupFunction = async () => {
      // Let's pretend functions setUpSomeResource and startSomeCronJob
      // are implemented below or imported from another file.
      someResource = await setUpSomeResource()
      startSomeCronJob()
    }

    export const getSomeResource = () => someResource
    src/queries.js
    import { getSomeResource } from './myServerSetupCode.js'

    ...

    export const someQuery = async (args, context) => {
      const someResource = getSomeResource()
      return queryDataFromSomeResource(args, someResource)
    }
    note

    The recommended way is to put the variable in the same module where you defined the setup function and then expose additional functions for reading those values, which you can then import directly from Operations and use.

    This effectively turns your module into a singleton whose construction is performed on server start.

    Read more about server setup function below.

    Middleware Config Function​

    You can configure the global middleware via the middlewareConfigFn. This will modify the middleware stack for all operations and APIs.

    Read more about middleware config function below.

    API Reference​

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      server: {
        setupFn: import { mySetupFunction } from "@src/myServerSetupCode.js",
        middlewareConfigFn: import { myMiddlewareConfigFn } from "@src/myServerSetupCode.js"
      }
    }

    app.server is a dictionary with the following fields:

    • setupFn: ExtImport​

      setupFn declares a function that will be executed on server start. This function is expected to be async and will be awaited before the server starts accepting any requests.

      It allows you to do any custom setup, e.g. setting up additional database/websockets or starting cron/scheduled jobs.

      The setupFn function receives the express.Application and the http.Server instances as part of its context. They can be useful for setting up any custom server logic.

      src/myServerSetupCode.js
      export const mySetupFunction = async () => {
        await setUpSomeResource()
      }

    • middlewareConfigFn: ExtImport​

      The import statement to an Express middleware config function. This is a global modification affecting all operations and APIs. See more in the configuring middleware section.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/project/starter-templates.html b/docs/0.14.0/project/starter-templates.html index 24b79351f1..39cdbecc70 100644 --- a/docs/0.14.0/project/starter-templates.html +++ b/docs/0.14.0/project/starter-templates.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.14.0

    Starter Templates

    We created a few starter templates to help you get started with Wasp. Check out the list below.

    Using a Template​

    Run wasp new to run the interactive mode for creating a new Wasp project.

    It will ask you for the project name, and then for the template to use:

    $ 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

    Available Templates​

    When you have a good idea for a new product, you don't want to waste your time on setting up common things like authentication, database, etc. That's why we created a few starter templates to help you get started with Wasp.

    OpenSaaS.sh template​

    SaaS Template

    Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check out https://opensaas.sh/ for more details.

    Features: Stripe Payments, OpenAI GPT API, Google Auth, SendGrid, Tailwind, & Cron Jobs

    Use this template:

    wasp new <project-name> -t saas

    Vector Similarity Search Template​

    Vector Similarity Search Template

    A template for generating embeddings and performing vector similarity search on your text data!

    Features: Embeddings & vector similarity search, OpenAI Embeddings API, Vector DB (Pinecone), Tailwind, Full-stack Type Safety

    Use this template:

    wasp new <project-name> -t embeddings

    Todo App w/ Typescript​

    A simple Todo App with Typescript and Full-stack Type Safety.

    Features: Auth (username/password), Full-stack Type Safety

    Use this template:

    wasp new <project-name> -t todo-ts

    AI Generated Starter 🤖​

    Using the same tech as used on https://usemage.ai/, Wasp generates your custom starter template based on your project description. It will automatically generate your data model, auth, queries, actions and React pages.

    You will need to provide your own OpenAI API key to be able to use this template.

    Features: Generated using OpenAI's GPT models, Auth (username/password), Queries, Actions, Pages, Full-stack Type Safety

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/project/static-assets.html b/docs/0.14.0/project/static-assets.html index b7a8ce4c3c..6925bcc848 100644 --- a/docs/0.14.0/project/static-assets.html +++ b/docs/0.14.0/project/static-assets.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.0

    Static Asset Handling

    Importing an Asset as URL​

    Importing a static asset (e.g. an image) will return its URL. For example:

    src/App.jsx
    import imgUrl from './img.png'

    function App() {
      return <img src={imgUrl} alt="img" />
    }

    For example, imgUrl will be /img.png during development, and become /assets/img.2d8efhg.png in the production build.

    This is what you want to use most of the time, as it ensures that the asset file exists and is included in the bundle.

    We are using Vite under the hood, read more about importing static assets in Vite's docs.

    The public Directory​

    If you have assets that are:

    • Never referenced in source code (e.g. robots.txt)
    • Must retain the exact same file name (without hashing)
    • ...or you simply don't want to have to import an asset first just to get its URL

    Then you can place the asset in the public directory at the root of your project:

    .
    └── public
        ├── favicon.ico
        └── robots.txt

    Assets in this directory will be served at root path / during development and copied to the root of the dist directory as-is.

    For example, if you have a file favicon.ico in the public directory, and your app is hosted at https://myapp.com, it will be made available at https://myapp.com/favicon.ico.

    Usage in client code

    Note that:

    • You should always reference public assets using root absolute path
      • for example, public/icon.png should be referenced in source code as /icon.png.
    • Assets in the public directory cannot be imported from .
    - - + + \ No newline at end of file diff --git a/docs/0.14.0/project/testing.html b/docs/0.14.0/project/testing.html index 50ffd325b3..5f16d123bc 100644 --- a/docs/0.14.0/project/testing.html +++ b/docs/0.14.0/project/testing.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.0

    Testing

    info

    Wasp is in beta, so keep in mind there might be some kinks / bugs, and possibly some changes with testing support in the future. If you encounter any issues, reach out to us on Discord and we will make sure to help you out!

    Testing Your React App​

    Wasp enables you to quickly and easily write both unit tests and React component tests for your frontend code. Because Wasp uses Vite, we support testing web apps through Vitest.

    Included Libraries

    vitest: Unit test framework with native Vite support.

    @vitest/ui: A nice UI for seeing your test results.

    jsdom: A web browser test environment for Node.js.

    @testing-library/react / @testing-library/jest-dom: Testing helpers.

    msw: A server mocking library.

    Writing Tests​

    For Wasp to pick up your tests, they should be placed within the src directory and use an extension that matches these glob patterns. Some of the file names that Wasp will pick up as tests:

    • yourFile.test.ts
    • YourComponent.spec.jsx

    Within test files, you can import your other source files as usual. For example, if you have a component Counter.jsx, you test it by creating a file in the same directory called Counter.test.jsx and import the component with import Counter from './Counter'.

    Running Tests​

    Running wasp test client will start Vitest in watch mode and recompile your Wasp project when changes are made.

    • If you want to see a real-time UI, pass --ui as an option.
    • To run the tests just once, use wasp test client run.

    All arguments after wasp test client are passed directly to the Vitest CLI, so check out their documentation for all of the options.

    Be Careful

    You should not run wasp test while wasp start is running. Both will try to compile your project to .wasp/out.

    React Testing Helpers​

    Wasp provides several functions to help you write React tests:

    • renderInContext: Takes a React component, wraps it inside a QueryClientProvider and Router, and renders it. This is the function you should use to render components in your React component tests.

      import { renderInContext } from "wasp/client/test";

      renderInContext(<MainPage />);

    • mockServer: Sets up the mock server and returns an object containing the mockQuery and mockApi utilities. This should be called outside of any test case, in each file that wants to use those helpers.

      import { mockServer } from "wasp/client/test";

      const { mockQuery, mockApi } = mockServer();

      • mockQuery: Takes a Wasp query to mock and the JSON data it should return.

        import { getTasks } from "wasp/client/operations";

        mockQuery(getTasks, []);
        • Helpful when your component uses useQuery.
        • Behind the scenes, Wasp uses msw to create a server request handle that responds with the specified data.
        • Mock are cleared between each test.

      • mockApi: Similar to mockQuery, but for APIs. Instead of a Wasp query, it takes a route containing an HTTP method and a path.

        import { HttpMethod } from "wasp/client";

        mockApi({ method: HttpMethod.Get, path: "/foor/bar" }, { res: "hello" });

    Testing Your Server-Side Code​

    Wasp currently does not provide a way to test your server-side code, but we will be adding support soon. You can track the progress at this GitHub issue and express your interest by commenting.

    Examples​

    You can see some tests in a Wasp project here.

    Client Unit Tests​

    src/helpers.js
    export function areThereAnyTasks(tasks) {
      return tasks.length === 0;
    }
    src/helpers.test.js
    import { test, expect } from "vitest";

    import { areThereAnyTasks } from "./helpers";

    test("areThereAnyTasks", () => {
      expect(areThereAnyTasks([])).toBe(false);
    });

    React Component Tests​

    src/Todo.jsx
    import { useQuery, getTasks } from "wasp/client/operations";

    const Todo = (_props) => {
      const { data: tasks } = useQuery(getTasks);
      return (
        <ul>
          {tasks &&
            tasks.map((task) => (
              <li key={task.id}>
                <input type="checkbox" value={task.isDone} />
                {task.description}
              </li>
            ))}
        </ul>
      );
    };
    src/Todo.test.jsx
    import { test, expect } from "vitest";
    import { screen } from "@testing-library/react";

    import { mockServer, renderInContext } from "wasp/client/test";
    import { getTasks } from "wasp/client/operations";
    import Todo from "./Todo";

    const { mockQuery } = mockServer();

    const mockTasks = [
      {
        id: 1,
        description: "test todo 1",
        isDone: true,
        userId: 1,
      },
    ];

    test("handles mock data", async () => {
      mockQuery(getTasks, mockTasks);

      renderInContext(<Todo />);

      await screen.findByText("test todo 1");

      expect(screen.getByRole("checkbox")).toBeChecked();

      screen.debug();
    });

    Testing With Mocked APIs​

    src/Todo.jsx
    import { api } from "wasp/client/api";

    const Todo = (_props) => {
      const [tasks, setTasks] = useState([]);
      useEffect(() => {
        api
          .get("/tasks")
          .then((res) => res.json())
          .then((tasks) => setTasks(tasks))
          .catch((err) => window.alert(err));
      });

      return (
        <ul>
          {tasks &&
            tasks.map((task) => (
              <li key={task.id}>
                <input type="checkbox" value={task.isDone} />
                {task.description}
              </li>
            ))}
        </ul>
      );
    };
    src/Todo.test.jsx
    import { test, expect } from "vitest";
    import { screen } from "@testing-library/react";

    import { mockServer, renderInContext } from "wasp/client/test";
    import Todo from "./Todo";

    const { mockApi } = mockServer();

    const mockTasks = [
      {
        id: 1,
        description: "test todo 1",
        isDone: true,
        userId: 1,
      },
    ];

    test("handles mock data", async () => {
      mockApi("/tasks", { res: mockTasks });

      renderInContext(<Todo />);

      await screen.findByText("test todo 1");

      expect(screen.getByRole("checkbox")).toBeChecked();

      screen.debug();
    });
    - - + + \ No newline at end of file diff --git a/docs/0.14.0/quick-start.html b/docs/0.14.0/quick-start.html index 08646fb08a..6224e43687 100644 --- a/docs/0.14.0/quick-start.html +++ b/docs/0.14.0/quick-start.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.14.0

    Quick Start

    Installation​

    Welcome, new Waspeteer 🐝!

    Let's create and run our first Wasp app in 3 short steps:

    1. To install Wasp on Linux / OSX / WSL (Windows), open your terminal and run:

      curl -sSL https://get.wasp-lang.dev/installer.sh | sh

      ℹ️ Wasp requires Node.js and will warn you if it is missing: check below for more details.

    2. Then, create a new app by running:

      wasp new

    3. Finally, run the app:

      cd <my-project-name>
      wasp start

    That's it 🎉 You have successfully created and served a new full-stack web app at http://localhost:3000 and Wasp is serving both frontend and backend for you.

    Something Unclear?

    Check More Details section below if anything went wrong with the installation, or if you have additional questions.

    Want an even faster start?

    Try out Wasp AI 🤖 to generate a new Wasp app in minutes just from a title and short description!

    Try Wasp Without Installing 🤔?

    Give Wasp a spin in the browser with GitHub Codespaces by following the intructions in our Tutorial App README

    What next?​

    • 👉 Check out the Todo App tutorial, which will take you through all the core features of Wasp! 👈
    • Setup your editor for working with Wasp.
    • Join us on Discord! Any feedback or questions you have, we are there for you.
    • Follow Wasp development by subscribing to our newsletter: https://wasp-lang.dev/#signup . We usually send 1 per month, and Matija does his best to unleash his creativity to make them engaging and fun to read :D!

    More details​

    Requirements​

    You must have Node.js (and NPM) installed on your machine and available in PATH. A version of Node.js must be >= 18.

    If you need it, we recommend using nvm for managing your Node.js installation version(s).

    A quick guide on installing/using nvm

    Install nvm via your OS package manager (apt, pacman, homebrew, ...) or via the nvm install script.

    Then, install a version of Node.js that you need:

    nvm install 20

    Finally, whenever you need to ensure a specific version of Node.js is used, run:

    nvm use 20

    to set the Node.js version for the current shell session.

    You can run

    node -v

    to check the version of Node.js currently being used in this shell session.

    Check NVM repo for more details: https://github.com/nvm-sh/nvm.

    Installation​

    Open your terminal and run:

    curl -sSL https://get.wasp-lang.dev/installer.sh | sh
    Running Wasp on Mac with Mx chip (arm64)

    Experiencing the 'Bad CPU type in executable' issue on a device with arm64 (Apple Silicon)? Given that the wasp binary is built for x86 and not for arm64 (Apple Silicon), you'll need to install Rosetta on your Mac if you are using a Mac with Mx (M1, M2, ...). Rosetta is a translation process that enables users to run applications designed for x86 on arm64 (Apple Silicon). To install Rosetta, run the following command in your terminal

    softwareupdate --install-rosetta

    Once Rosetta is installed, you should be able to run Wasp without any issues.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/telemetry.html b/docs/0.14.0/telemetry.html index 14afc225d6..7326684c1b 100644 --- a/docs/0.14.0/telemetry.html +++ b/docs/0.14.0/telemetry.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.14.0

    Telemetry

    Overview​

    The term telemetry refers to the collection of certain usage data to help improve the quality of a piece of software (in this case, Wasp).

    Our telemetry implementation is anonymized and very limited in its scope, focused on answering following questions:

    • How many people and how often: tried to install Wasp, use Wasp, have built a Wasp app, or have deployed one?
    • How many projects are created with Wasp?

    When and what is sent?​

    • Information is sent via HTTPS request when wasp CLI command is invoked. Information is sent no more than twice in a period of 12 hours (sending is paused for 12 hours after last invocation, separately for wasp build command and for all other commands). Exact information as it is sent:
      {
        // Randomly generated, non-identifiable UUID representing a user.
        "distinct_id": "bf3fa7a8-1c11-4f82-9542-ec1a2d28786b",
        // Non-identifiable hash representing a project.
        "project_hash": "6d7e561d62b955d1",
        // True if command was `wasp build`, false otherwise.
        "is_build": true,
        // Captures `wasp deploy ...` args, but only those from the limited, pre-defined list of keywords.
        // Those are "fly", "setup", "create-db", "deploy" and "cmd". Everything else is ommited.
        "deploy_cmd_args": "fly;deploy",
        "wasp_version": "0.1.9.1",
        "os": "linux",
        // "CI" if running on CI, and whatever is the content of "WASP_TELEMETRY_CONTEXT" env var.
        // We use this to track when execution is happening in some special context, like on Gitpod, Replit or similar.
        "context": "CI"
      }
    • Information is also sent once via HTTPS request when wasp is installed via install.sh script. Exact information as it is sent:
      {
        // Randomly generated id.
        "distinct_id": "274701613078193779564259",
        "os": "linux"
      }

    Opting out​

    You sharing the telemetry data with us means a lot to us, since it helps us understand how popular Wasp is, how it is being used, how the changes we are doing affect usage, how many new vs old users there are, and just in general how Wasp is doing. We look at these numbers every morning and they drive us to make Wasp better.

    However, if you wish to opt-out of telemetry, we understand! You can do so by setting the WASP_TELEMETRY_DISABLE environment variable to any value, e.g.:

    export WASP_TELEMETRY_DISABLE=1

    Future plans​

    We don't have this implemented yet, but the next step will be to make telemetry go in two directions -> instead of just sending usage data to us, it will also at the same time check for any messages from our side (e.g. notification about new version of Wasp, or a security notice). Link to corresponding github issue.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/tutorial/actions.html b/docs/0.14.0/tutorial/actions.html index 5e04beeb7c..cee4ed5319 100644 --- a/docs/0.14.0/tutorial/actions.html +++ b/docs/0.14.0/tutorial/actions.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.14.0

    6. Modifying Data

    In the previous section, you learned about using Queries to fetch data. Let's now learn about Actions so you can add and update tasks in the database.

    In this section, you will create:

    1. A Wasp Action that creates a new task.
    2. A React form that calls that Action when the user creates a task.

    Creating a New Action​

    Creating an Action is very similar to creating a Query.

    Declaring an Action​

    We must first declare the Action in main.wasp:

    main.wasp
    // ...

    action createTask {
      fn: import { createTask } from "@src/actions",
      entities: [Task]
    }

    Implementing an Action​

    Let's now define a function for our createTask Action:

    src/actions.js
    export const createTask = async (args, context) => {
      return context.entities.Task.create({
        data: { description: args.description },
      })
    }
    tip

    We put the function in a new file src/actions.ts, but we could have put it anywhere we wanted! There are no limitations here, as long as the declaration in the Wasp file imports it correctly and the file is located within src directory.

    Invoking the Action on the Client​

    Start by defining a form for creating new tasks.

    src/MainPage.jsx
    import { 
      createTask, 
      getTasks, 
      useQuery 
    } from 'wasp/client/operations'

    // ... MainPage, TaskView, TaskList ...

    const NewTaskForm = () => {
      const handleSubmit = async (event) => {
        event.preventDefault()
        try {
          const target = event.target
          const description = target.description.value
          target.reset()
          await createTask({ description })
        } catch (err) {
          window.alert('Error: ' + err.message)
        }
      }

      return (
        <form onSubmit={handleSubmit}>
          <input name="description" type="text" defaultValue="" />
          <input type="submit" value="Create task" />
        </form>
      )
    }

    Unlike Queries, you can call Actions directly (without wrapping them in a hook) because they don't need reactivity. The rest is just regular React code.

    All that's left now is adding this form to the page component:

    src/MainPage.jsx
    import {
      createTask,
      getTasks,
      useQuery
    } from 'wasp/client/operations'

    const MainPage = () => {
      const { data: tasks, isLoading, error } = useQuery(getTasks)

      return (
        <div>
          <NewTaskForm />

          {tasks && <TasksList tasks={tasks} />}

          {isLoading && 'Loading...'}
          {error && 'Error: ' + error}
        </div>
      )
    }

    // ... TaskView, TaskList, NewTaskForm ...

    Great work!

    You now have a form for creating new tasks.

    Try creating a "Build a Todo App in Wasp" task and see it appear in the list below. The task is created on the server and saved in the database.

    Try refreshing the page or opening it in another browser. You'll see the tasks are still there!

    Todo App - creating new task

    Automatic Query Invalidation

    When you create a new task, the list of tasks is automatically updated to display the new task, even though you haven't written any code that does that! Wasp handles these automatic updates under the hood.

    When you declared the getTasks and createTask operations, you specified that they both use the Task entity. So when createTask is called, Wasp knows that the data getTasks fetches may have changed and automatically updates it in the background. This means that out of the box, Wasp keeps all your queries in sync with any changes made through Actions.

    This behavior is convenient as a default but can cause poor performance in large apps. While there is no mechanism for overriding this behavior yet, it is something that we plan to include in Wasp in the future. This feature is tracked here.

    A Second Action​

    Our Todo app isn't finished if you can't mark a task as done.

    We'll create a new Action to update a task's status and call it from React whenever a task's checkbox is toggled.

    Since we've already created one task together, try to create this one yourself. It should be an Action named updateTask that receives the task's id and its isDone status. You can see our implementation below.

    Solution

    Declaring the Action in main.wasp:

    main.wasp
    // ...

    action updateTask {
      fn: import { updateTask } from "@src/actions",
      entities: [Task]
    }

    Implementing the Action on the server:

    src/actions.js
    // ...

    export const updateTask = async ({ id, isDone }, context) => {
      return context.entities.Task.update({
        where: { id },
        data: {
          isDone: isDone,
        },
      })
    }

    You can now call updateTask from the React component:

    src/MainPage.jsx
    // ...
    import {
      updateTask,
      createTask,
      getTasks,
      useQuery,
    } from 'wasp/client/operations'

    // ... MainPage ...

    const TaskView = ({ task }) => {
      const handleIsDoneChange = async (event) => {
        try {
          await updateTask({
            id: task.id,
            isDone: event.target.checked,
          })
        } catch (error) {
          window.alert('Error while updating task: ' + error.message)
        }
      }

      return (
        <div>
          <input
            type="checkbox"
            id={String(task.id)}
            checked={task.isDone}
            onChange={handleIsDoneChange}
          />
          {task.description}
        </div>
      )
    }
    // ... TaskList, NewTaskForm ...

    Awesome! You can now mark this task as done.

    It's time to make one final addition to your app: supporting multiple users.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/tutorial/auth.html b/docs/0.14.0/tutorial/auth.html index 24f177bb1c..1637bb35a9 100644 --- a/docs/0.14.0/tutorial/auth.html +++ b/docs/0.14.0/tutorial/auth.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.0

    7. Adding Authentication

    Most modern apps need a way to create and authenticate users. Wasp makes this as easy as possible with its first-class auth support.

    To add users to your app, you must:

    • Create a User Entity.
    • Tell Wasp to use the Username and Password authentication.
    • Add login and signup pages.
    • Update the main page to require authentication.
    • Add a relation between User and Task entities.
    • Modify your Queries and Actions so users can only see and modify their tasks.
    • Add a logout button.

    Creating a User Entity​

    Since Wasp manages authentication, it will create the auth related entities for you in the background. Nothing to do here!

    You must only add the User Entity to keep track of who owns which tasks:

    schema.prisma
    // ...

    model User {
      id Int @id @default(autoincrement())
    }

    Adding Auth to the Project​

    Next, tell Wasp to use full-stack authentication:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.14.0"
      },
      title: "TodoApp",
      auth: {
        // Tells Wasp which entity to use for storing users.
        userEntity: User,
        methods: {
          // Enable username and password auth.
          usernameAndPassword: {}
        },
        // We'll see how this is used in a bit.
        onAuthFailedRedirectTo: "/login"
      }
    }

    // ...

    Don't forget to update the database schema by running:

    wasp db migrate-dev

    By doing this, Wasp will create:

    • Auth UI with login and signup forms.
    • A logout() action.
    • A React hook useAuth().
    • context.user for use in Queries and Actions.
    info

    Wasp also supports authentication using Google, GitHub, and email, with more on the way!

    Adding Login and Signup Pages​

    Wasp creates the login and signup forms for us, but we still need to define the pages to display those forms on. We'll start by declaring the pages in the Wasp file:

    main.wasp
    // ...

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage"
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage"
    }

    Great, Wasp now knows these pages exist!

    Here's the React code for the pages you've just imported:

    src/LoginPage.jsx
    import { Link } from 'react-router-dom'
    import { LoginForm } from 'wasp/client/auth'

    export const LoginPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <LoginForm />
          <br />
          <span>
            I don't have an account yet (<Link to="/signup">go to signup</Link>).
          </span>
        </div>
      )
    }

    The signup page is very similar to the login page:

    src/SignupPage.jsx
    import { Link } from 'react-router-dom'
    import { SignupForm } from 'wasp/client/auth'

    export const SignupPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <SignupForm />
          <br />
          <span>
            I already have an account (<Link to="/login">go to login</Link>).
          </span>
        </div>
      )
    }

    Update the Main Page to Require Auth​

    We don't want users who are not logged in to access the main page, because they won't be able to create any tasks. So let's make the page private by requiring the user to be logged in:

    main.wasp
    // ...

    page MainPage {
      authRequired: true,
      component: import { MainPage } from "@src/MainPage"
    }

    Now that auth is required for this page, unauthenticated users will be redirected to /login, as we specified with app.auth.onAuthFailedRedirectTo.

    Additionally, when authRequired is true, the page's React component will be provided a user object as prop.

    src/MainPage.jsx
    export const MainPage = ({ user }) => {
      // Do something with the user
      // ...
    }

    Ok, time to test this out. Navigate to the main page (/) of the app. You'll get redirected to /login, where you'll be asked to authenticate.

    Since we just added users, you don't have an account yet. Go to the signup page and create one. You'll be sent back to the main page where you will now be able to see the TODO list!

    Let's check out what the database looks like. Start the Prisma Studio:

    wasp db studio
    Database demonstration - password hashing

    You'll notice that we now have a User entity in the database alongside the Task entity.

    However, you will notice that if you try logging in as different users and creating some tasks, all users share the same tasks. That's because you haven't yet updated the queries and actions to have per-user tasks. Let's do that next.

    You might notice some extra Prisma models like Auth, AuthIdentity and Session that Wasp created for you. You don't need to care about these right now, but if you are curious, you can read more about them here.

    Defining a User-Task Relation​

    First, let's define a one-to-many relation between users and tasks (check the Prisma docs on relations):

    schema.prisma
    // ...

    model User {
      id    Int    @id @default(autoincrement())
      tasks Task[]
    }

    model Task {
      id          Int     @id @default(autoincrement())
      description String
      isDone      Boolean @default(false)
      user        User?   @relation(fields: [userId], references: [id])
      userId      Int?
    }

    As always, you must migrate the database after changing the Entities:

    wasp db migrate-dev
    note

    We made user and userId in Task optional (via ?) because that allows us to keep the existing tasks, which don't have a user assigned, in the database.

    This isn't recommended because it allows an unwanted state in the database (what is the purpose of the task not belonging to anybody?) and normally we would not make these fields optional.

    Instead, we would do a data migration to take care of those tasks, even if it means just deleting them all. However, for this tutorial, for the sake of simplicity, we will stick with this.

    Updating Operations to Check Authentication​

    Next, let's update the queries and actions to forbid access to non-authenticated users and to operate only on the currently logged-in user's tasks:

    src/queries.js
    import { HttpError } from 'wasp/server'

    export const getTasks = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.findMany({
        where: { user: { id: context.user.id } },
        orderBy: { id: 'asc' },
      })
    }
    src/actions.js
    import { HttpError } from 'wasp/server'

    export const createTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.create({
        data: {
          description: args.description,
          user: { connect: { id: context.user.id } },
        },
      })
    }

    export const updateTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.updateMany({
        where: { id: args.id, user: { id: context.user.id } },
        data: { isDone: args.isDone },
      })
    }
    note

    Due to how Prisma works, we had to convert update to updateMany in updateTask action to be able to specify the user id in where.

    With these changes, each user should have a list of tasks that only they can see and edit.

    Try playing around, adding a few users and some tasks for each of them. Then open the DB studio:

    wasp db studio
    Database demonstration

    You will see that each user has their tasks, just as we specified in our code!

    Logout Button​

    Last, but not least, let's add the logout functionality:

    src/MainPage.jsx
    // ...
    import { logout } from 'wasp/client/auth'
    //...

    const MainPage = () => {
      // ...
      return (
        <div>
          // ...
          <button onClick={logout}>Logout</button>
        </div>
      )
    }

    This is it, we have a working authentication system, and our Todo app is multi-user!

    What's Next?​

    We did it 🎉 You've followed along with this tutorial to create a basic Todo app with Wasp.

    You should be ready to learn about more complicated features and go more in-depth with the features already covered. Scroll through the sidebar on the left side of the page to see every feature Wasp has to offer. Or, let your imagination run wild and start building your app! ✨

    Looking for inspiration?

    note

    If you notice that some of the features you'd like to have are missing, or have any other kind of feedback, please write to us on Discord or create an issue on Github, so we can learn which features to add/improve next 🙏

    If you would like to contribute or help to build a feature, let us know! You can find more details on contributing here.

    Oh, and do subscribe to our newsletter! We usually send one per month, and Matija does his best to unleash his creativity to make them engaging and fun to read :D!

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/tutorial/create.html b/docs/0.14.0/tutorial/create.html index 7175d8c347..5e243789a8 100644 --- a/docs/0.14.0/tutorial/create.html +++ b/docs/0.14.0/tutorial/create.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.14.0

    1. Creating a New Project

    info

    You'll need to have the latest version of Wasp installed locally to follow this tutorial. If you haven't installed it yet, check out the QuickStart guide!

    In this section, we'll guide you through the process of creating a simple Todo app with Wasp. In the process, we'll take you through the most important and useful features of Wasp.

    How Todo App will work once it is done

    If you get stuck at any point (or just want to chat), reach out to us on Discord and we will help you!

    You can find the complete code of the app we're about to build here.

    Creating a Project​

    To setup a new Wasp project, run the following command in your terminal

    $ wasp new TodoApp

    Enter the newly created directory and start the development server:

    $ cd TodoApp
    $ wasp start

    wasp start will take a bit of time to start the server the first time you run it in a new project.

    You will see log messages from the client, server, and database setting themselves up. When everything is ready, a new tab should open in your browser at http://localhost:3000 with a simple placeholder page:

    Screenshot of new Wasp app

    Wasp has generated for you the full front-end and back-end code of the app! Next, we'll take a closer look at how the project is structured.

    A note on supported languages​

    Wasp supports both JavaScript and TypeScript out of the box, but you are free to choose between or mix JavaScript and TypeScript as you see fit.

    We'll provide you with both JavaScript and TypeScript code in this tutorial. Code blocks will have a toggle to switch between vanilla JavaScript and TypeScript.

    Try it out:

    Welcome to JavaScript!

    You are now reading the JavaScript version of the docs. The site will remember your preference as you switch pages.

    You'll have a chance to change the language on every code snippet - both the snippets and the text will update accordingly.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/tutorial/entities.html b/docs/0.14.0/tutorial/entities.html index 78de87f3d5..274e4c6097 100644 --- a/docs/0.14.0/tutorial/entities.html +++ b/docs/0.14.0/tutorial/entities.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.0

    4. Database Entities

    Entities are one of the most important concepts in Wasp and are how you define what gets stored in the database.

    Wasp uses Prisma to talk to the database, and you define Entities by defining Prisma models in the schema.prisma file.

    Since our Todo app is all about tasks, we'll define a Task entity by adding a Task model in the schema.prisma file:

    schema.prisma
    // ...

    model Task {
        id          Int     @id @default(autoincrement())
        description String
        isDone      Boolean @default(false)
    }
    note

    Read more about how Wasp Entities work in the Entities section or how Wasp uses the schema.prisma file in the Prisma Schema File section.

    To update the database schema to include this entity, stop the wasp start process, if it's running, and run:

    wasp db migrate-dev

    You'll need to do this any time you change an entity's definition. It instructs Prisma to create a new database migration and apply it to the database.

    To take a look at the database and the new Task entity, run:

    wasp db studio

    This will open a new page in your browser to view and edit the data in your database.

    Todo App - Db studio showing Task schema

    Click on the Task entity and check out its fields! We don't have any data in our database yet, but we are about to change that.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/tutorial/pages.html b/docs/0.14.0/tutorial/pages.html index 0dd9c5c0b1..7dd7ec5a91 100644 --- a/docs/0.14.0/tutorial/pages.html +++ b/docs/0.14.0/tutorial/pages.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.14.0

    3. Pages & Routes

    In the default main.wasp file created by wasp new, there is a page and a route declaration:

    main.wasp
    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      // We specify that the React implementation of the page is exported from 
      // `src/MainPage.jsx`. This statement uses standard JS import syntax.
      // Use `@src` to reference files inside the `src` folder.
      component: import { MainPage } from "@src/MainPage"
    }

    Together, these declarations tell Wasp that when a user navigates to /, it should render the named export from src/MainPage.tsx.

    The MainPage Component​

    Let's take a look at the React component referenced by the page declaration:

    src/MainPage.jsx
    import waspLogo from './waspLogo.png'
    import './Main.css'

    export const MainPage = () => {
      // ...
    }

    This is a regular functional React component. It also uses the CSS file and a logo image that sit next to it in the src folder.

    That is all the code you need! Wasp takes care of everything else necessary to define, build, and run the web app.

    Keep Wasp start running

    wasp start automatically picks up the changes you make, regenerates the code, and restarts the app. So keep it running in the background.

    It also improves your experience by tracking the working directory and ensuring the generated code/types are up to date with your changes.

    Adding a Second Page​

    To add more pages, you can create another set of page and route declarations. You can even add parameters to the URL path, using the same syntax as React Router. Let's test this out by adding a new page:

    main.wasp
    route HelloRoute { path: "/hello/:name", to: HelloPage }
    page HelloPage {
      component: import { HelloPage } from "@src/HelloPage"
    }

    When a user visits /hello/their-name, Wasp will render the component exported from src/HelloPage.tsx and pass the URL parameter the same way as in React Router:

    src/HelloPage.jsx
    export const HelloPage = (props) =>  {
      return <div>Here's {props.match.params.name}!</div>
    }

    Now you can visit /hello/johnny and see "Here's johnny!"

    Cleaning Up​

    Now that you've seen how Wasp deals with Routes and Pages, it's finally time to build the Todo app.

    Start by cleaning up the starter project and removing unnecessary code and files.

    First, remove most of the code from the MainPage component:

    src/MainPage.jsx
    export const MainPage = () => {
      return <div>Hello world!</div>
    }

    At this point, the main page should look like this:

    Todo App - Hello World

    You can now delete redundant files: src/Main.css, src/waspLogo.png, and src/HelloPage.tsx (we won't need this page for the rest of the tutorial).

    Since src/HelloPage.tsx no longer exists, remove its route and page declarations from the main.wasp file.

    Your Wasp file should now look like this:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.14.0"
      },
      title: "TodoApp"
    }

    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      component: import { MainPage } from "@src/MainPage"
    }

    Excellent work!

    You now have a basic understanding of Wasp and are ready to start building your TodoApp. We'll implement the app's core features in the following sections.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/tutorial/project-structure.html b/docs/0.14.0/tutorial/project-structure.html index 33f0e87f91..b94a38350c 100644 --- a/docs/0.14.0/tutorial/project-structure.html +++ b/docs/0.14.0/tutorial/project-structure.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -30,7 +30,7 @@ We'll keep it simple by placing everything in the root src directory.

    Many other files (e.g., tsconfig.json, vite-env.d.ts, .wasproot, etc.) help Wasp and the IDE improve your development experience with autocompletion, IntelliSense, and error reporting.

    The vite.config.ts file is used to configure Vite, Wasp's build tool of choice. We won't be configuring Vite in this tutorial, so you can safely ignore the file. Still, if you ever end up wanting more control over Vite, you'll find everything you need to know in custom Vite config docs.

    The schema.prisma file is where you define your database schema using Prisma. We'll cover this a bit later in the tutorial.

    The most important file in the project is main.wasp. Wasp uses the configuration within it to perform its magic. Based on what you write, it generates a bunch of code for your database, server-client communication, React routing, and more.

    Let's take a closer look at main.wasp

    main.wasp​

    main.wasp is your app's definition file. It defines the app's central components and helps Wasp to do a lot of the legwork for you.

    The file is a list of declarations. Each declaration defines a part of your app.

    The default main.wasp file generated with wasp new on the previous page looks like this:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.14.0" // Pins the version of Wasp to use.
      },
      title: "TodoApp" // Used as the browser tab title. Note that all strings in Wasp are double quoted!
    }

    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      // We specify that the React implementation of the page is exported from
      // `src/MainPage.jsx`. This statement uses standard JS import syntax.
      // Use `@src` to reference files inside the `src` folder.
      component: import { MainPage } from "@src/MainPage"
    }

    This file uses three declaration types:

    • app: Top-level configuration information about your app.

    • route: Describes which path each page should be accessible from.

    • page: Defines a web page and the React component that gets rendered when the page is loaded.

    In the next section, we'll explore how route and page work together to build your web app.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/tutorial/queries.html b/docs/0.14.0/tutorial/queries.html index 831593409f..fa29f5daaa 100644 --- a/docs/0.14.0/tutorial/queries.html +++ b/docs/0.14.0/tutorial/queries.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.0

    5. Querying the Database

    We want to know which tasks we need to do, so let's list them!

    The primary way of working with Entities in Wasp is with Queries and Actions, collectively known as Operations.

    Queries are used to read an entity, while Actions are used to create, modify, and delete entities. Since we want to list the tasks, we'll want to use a Query.

    To list the tasks, you must:

    1. Create a Query that fetches the tasks from the database.
    2. Update the MainPage.tsx to use that Query and display the results.

    Defining the Query​

    We'll create a new Query called getTasks. We'll need to declare the Query in the Wasp file and write its implementation in .

    Declaring a Query​

    We need to add a query declaration to main.wasp so that Wasp knows it exists:

    main.wasp
    // ...

    query getTasks {
      // Specifies where the implementation for the query function is.
      // The path `@src/queries` resolves to `src/queries.js`.
      // No need to specify an extension.
      fn: import { getTasks } from "@src/queries",
      // Tell Wasp that this query reads from the `Task` entity. Wasp will
      // automatically update the results of this query when tasks are modified.
      entities: [Task]
    }

    Implementing a Query​

    src/queries.js
    export const getTasks = async (args, context) => {
      return context.entities.Task.findMany({
        orderBy: { id: 'asc' },
      })
    }

    Query function parameters:

    • args: object

      The arguments the caller passes to the Query.

    • context

      An object with extra information injected by Wasp. Its type depends on the Query declaration.

    Since the Query declaration in main.wasp says that the getTasks Query uses Task entity, Wasp injected a Prisma client for the Task entity as context.entities.Task - we used it above to fetch all the tasks from the database.

    info

    Queries and Actions are NodeJS functions executed on the server.

    Invoking the Query On the Frontend​

    While we implement Queries on the server, Wasp generates client-side functions that automatically take care of serialization, network calls, and cache invalidation, allowing you to call the server code like it's a regular function.

    This makes it easy for us to use the getTasks Query we just created in our React component:

    src/MainPage.jsx
    import { getTasks, useQuery } from 'wasp/client/operations'

    export const MainPage = () => {
      const { data: tasks, isLoading, error } = useQuery(getTasks)

      return (
        <div>
          {tasks && <TasksList tasks={tasks} />}

          {isLoading && 'Loading...'}
          {error && 'Error: ' + error}
        </div>
      )
    }

    const TaskView = ({ task }) => {
      return (
        <div>
          <input type="checkbox" id={String(task.id)} checked={task.isDone} />
          {task.description}
        </div>
      )
    }

    const TasksList = ({ tasks }) => {
      if (!tasks?.length) return <div>No tasks</div>

      return (
        <div>
          {tasks.map((task, idx) => (
            <TaskView task={task} key={idx} />
          ))}
        </div>
      )
    }

    Most of this code is regular React, the only exception being the special wasp imports:

    We could have called the Query directly using getTasks(), but the useQuery hook makes it reactive: React will re-render the component every time the Query changes. Remember that Wasp automatically refreshes Queries whenever the data is modified.

    With these changes, you should be seeing the text "No tasks" on the screen:

    Todo App - No Tasks

    We'll create a form to add tasks in the next step 🪄

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/vision.html b/docs/0.14.0/vision.html index 9cd57c46bc..e1c7bf52fb 100644 --- a/docs/0.14.0/vision.html +++ b/docs/0.14.0/vision.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -33,7 +33,7 @@ They can be used inline (mixed with Wasp code) or provided via external files.
  • Has hatches (escape mechanisms) that allow you to customize your web app in all the right places, but remain hidden until you need them.
  • Entity (data model) is a first-class citizen - defined via custom Wasp syntax and it integrates very closely with the rest of the features, serving as one of the central concepts around which everything is built.
  • Out of the box support for CRUD UI based on the Entities, to get you quickly going, but also customizable to some level.
  • "Smart" operations (queries and actions) that in most cases automatically figure out when to update, and if not it is easy to define custom logic to compensate for that. User worries about client-server gap as little as possible.
  • Support, directly in Wasp, for declaratively defining simple components and operations.
  • Besides Wasp as a programming language, there will also be a visual builder that generates/edits Wasp code, allowing non-developers to participate in development. Since Wasp is declarative, we imagine such builder to naturally follow from Wasp language.
  • Server side rendering, caching, packaging, security, ... -> all those are taken care of by Wasp. You tell Wasp what you want, and Wasp figures out how to do it.
  • As simple deployment to production/staging as it gets.
  • While it comes with the official implementation(s), Wasp language will not be coupled with the single implementation. Others can provide implementations that compile to different web app stacks.
    • - - + + \ No newline at end of file diff --git a/docs/0.14.0/wasp-ai/creating-new-app.html b/docs/0.14.0/wasp-ai/creating-new-app.html index ebd48b16fe..2bf0273e2e 100644 --- a/docs/0.14.0/wasp-ai/creating-new-app.html +++ b/docs/0.14.0/wasp-ai/creating-new-app.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.14.0

    Creating New App with AI

    Wasp comes with its own AI: Wasp AI, aka Mage (Magic web App GEnerator).

    Wasp AI allows you to create a new Wasp app from only a title and a short description (using GPT in the background)!

    There are two main ways to create a new Wasp app with Wasp AI:

    1. Free, open-source online app usemage.ai.
    2. Running wasp new on your machine and picking AI generation. For this you need to provide your own OpenAI API keys, but it allows for more flexibility (choosing GPT models).

    They both use the same logic in the background, so both approaches are equally "smart", the difference is just in the UI / settings.

    info

    Wasp AI is an experimental feature. Apps that Wasp AI generates can have mistakes (proportional to their complexity), but even then they can often serve as a great starting point (once you fix the mistakes) or an interesting way to explore how to implement stuff in Wasp.

    usemage.ai​

    1. Describe your app 2. Pick the color 3. Generate your app 🚀

    Mage is an open-source app with which you can create new Wasp apps from just a short title and description.

    It is completely free for you - it uses our OpenAI API keys and we take on the costs.

    Once you provide an app title, app description, and choose some basic settings, your new Wasp app will be created for you in a matter of minutes and you will be able to download it to your machine and keep working on it!

    If you want to know more, check this blog post for more details on how Mage works, or this blog post for a high-level overview of how we implemented it.

    Wasp CLI​

    You can create a new Wasp app using Wasp AI by running wasp new in your terminal and picking AI generation.

    If you don't have them set yet, wasp will ask you to provide (via ENV vars) your OpenAI API keys (which it will use to query GPT).

    Then, after providing a title and description for your Wasp app, the new app will be generated on your disk!

    wasp-cli-ai-input wasp-cli-ai-generation

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/wasp-ai/developing-existing-app.html b/docs/0.14.0/wasp-ai/developing-existing-app.html index 26efb676c0..63483b0565 100644 --- a/docs/0.14.0/wasp-ai/developing-existing-app.html +++ b/docs/0.14.0/wasp-ai/developing-existing-app.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.14.0

    Developing Existing App with AI

    While Wasp AI doesn't at the moment offer any additional help for developing your Wasp app with AI beyond initial generation, this is something we are exploring actively.

    In the meantime, while waiting for Wasp AI to add support for this, we suggest checking out aider, which is an AI pair programming tool in your terminal. This is a third-party tool, not affiliated with Wasp in any way, but we and some of Wasp users have found that it can be helpful when working on Wasp apps.

    - - + + \ No newline at end of file diff --git a/docs/0.14.0/writingguide.html b/docs/0.14.0/writingguide.html index 796b5e4159..83aea8b4fd 100644 --- a/docs/0.14.0/writingguide.html +++ b/docs/0.14.0/writingguide.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -53,7 +53,7 @@ Many of our titles are currently in title-case, we should start phasing those out.
  • Use the Oxford comma (e.g., "a, b, and c" instead of "a, b and c"). Why the Oxford comma is important

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

    Linking to pages in the docs​

    Always use relative links (e.g. ../../overview.md) to link to other pages, unless you are writing a reusable snippet.

    Never use absolute links starting with /docs because they break our versioned docs, instead use links "absolute to the file root".

    Writing a link "absolute to the file root":

    1. Write an absolute link, start from the file root (e.g. / represents the docs folder)
    2. Include the extension (e.g. .md)

    For example, /docs/introduction should be written as /introduction/introduction.md because this file is located at ./docs/introduction/introduction.md.

    Or another example /docs/auth/entities#accessing-the-auth-fields becomes /auth/entities/entities.md#accessing-the-auth-fields. This file is located at ./docs/auth/entities/entities.md.

    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 d1cc091542..69590b500d 100644 --- a/docs/advanced/accessing-app-config.html +++ b/docs/advanced/accessing-app-config.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -36,7 +36,7 @@ Wasp automatically sets it during development when you run wasp start.
    In production, it should contain the value of your server's URL as the user's browser sees it (i.e., with the DNS and proxies considered).

    You can access it like this:

    import { config } from 'wasp/client'

    console.log(config.apiUrl)
    - - + + \ No newline at end of file diff --git a/docs/advanced/apis.html b/docs/advanced/apis.html index 003b542a98..f189ce12dc 100644 --- a/docs/advanced/apis.html +++ b/docs/advanced/apis.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.15.0

    Custom HTTP API Endpoints

    In Wasp, the default client-server interaction mechanism is through Operations. However, if you need a specific URL method/path, or a specific response, Operations may not be suitable for you. For these cases, you can use an api. Best of all, they should look and feel very familiar.

    How to Create an API​

    APIs are used to tie a JS function to a certain endpoint e.g. POST /something/special. They are distinct from Operations and have no client-side helpers (like useQuery).

    To create a Wasp API, you must:

    1. Declare the API in Wasp using the api declaration
    2. Define the API's NodeJS implementation

    After completing these two steps, you'll be able to call the API from the client code (via our Axios wrapper), or from the outside world.

    Declaring the API in Wasp​

    First, we need to declare the API in the Wasp file and you can easily do this with the api declaration:

    main.wasp
    // ...

    api fooBar { // APIs and their implementations don't need to (but can) have the same name.
      fn: import { fooBar } from "@src/apis",
      httpRoute: (GET, "/foo/bar")
    }

    Read more about the supported fields in the API Reference.

    Defining the API's NodeJS Implementation​

    After you defined the API, it should be implemented as a NodeJS function that takes three arguments:

    1. req: Express Request object
    2. res: Express Response object
    3. context: An additional context object injected into the API by Wasp. This object contains user session information, as well as information about entities. The examples here won't use the context for simplicity purposes. You can read more about it in the section about using entities in APIs.
    src/apis.js
    export const fooBar = (req, res, context) => {
      res.set("Access-Control-Allow-Origin", "*"); // Example of modifying headers to override Wasp default CORS middleware.
      res.json({ msg: `Hello, ${context.user ? "registered user" : "stranger"}!` });
    };

    Using the API​

    Using the API externally​

    To use the API externally, you simply call the endpoint using the method and path you used.

    For example, if your app is running at https://example.com then from the above you could issue a GET to https://example/com/foo/callback (in your browser, Postman, curl, another web service, etc.).

    Using the API from the Client​

    To use the API from your client, including with auth support, you can import the Axios wrapper from wasp/client/api and invoke a call. For example:

    src/pages/SomePage.jsx
    import React, { useEffect } from "react";
    import { api } from "wasp/client/api";

    async function fetchCustomRoute() {
      const res = await api.get("/foo/bar");
      console.log(res.data);
    }

    export const Foo = () => {
      useEffect(() => {
        fetchCustomRoute();
      }, []);

      return <>// ...</>;
    };

    Making Sure CORS Works​

    APIs are designed to be as flexible as possible, hence they don't utilize the default middleware like Operations do. As a result, to use these APIs on the client side, you must ensure that CORS (Cross-Origin Resource Sharing) is enabled.

    You can do this by defining custom middleware for your APIs in the Wasp file.

    For example, an apiNamespace is a simple declaration used to apply some middlewareConfigFn to all APIs under some specific path:

    main.wasp
    apiNamespace fooBar {
      middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@src/apis",
      path: "/foo"
    }

    And then in the implementation file:

    src/apis.js
    export const apiMiddleware = (config) => {
      return config;
    };

    We are returning the default middleware which enables CORS for all APIs under the /foo path.

    For more information about middleware configuration, please see: Middleware Configuration

    Using Entities in APIs​

    In many cases, resources used in APIs will be Entities. To use an Entity in your API, add it to the api declaration in Wasp:

    main.wasp
    api fooBar {
      fn: import { fooBar } from "@src/apis",
      entities: [Task],
      httpRoute: (GET, "/foo/bar")
    }

    Wasp will inject the specified Entity into the APIs context argument, giving you access to the Entity's Prisma API:

    src/apis.js
    export const fooBar = (req, res, context) => {
      res.json({ count: await context.entities.Task.count() });
    };

    The object context.entities.Task exposes prisma.task from Prisma's CRUD API.

    API Reference​

    main.wasp
    api fooBar {
      fn: import { fooBar } from "@src/apis",
      httpRoute: (GET, "/foo/bar"),
      entities: [Task],
      auth: true,
      middlewareConfigFn: import { apiMiddleware } from "@src/apis"
    }

    The api declaration has the following fields:

    • fn: ExtImport required

      The import statement of the APIs NodeJs implementation.

    • httpRoute: (HttpMethod, string) required

      The HTTP (method, path) pair, where the method can be one of:

      • ALL, GET, POST, PUT or DELETE
      • and path is an Express path string.

    • entities: [Entity]

      A list of entities you wish to use inside your API. You can read more about it here.

    • auth: bool

      If auth is enabled, this will default to true and provide a context.user object. If you do not wish to attempt to parse the JWT in the Authorization Header, you should set this to false.

    • middlewareConfigFn: ExtImport

      The import statement to an Express middleware config function for this API. See more in middleware section of the docs.

    - - + + \ No newline at end of file diff --git a/docs/advanced/deployment/cli.html b/docs/advanced/deployment/cli.html index a19497ee5d..517e26619d 100644 --- a/docs/advanced/deployment/cli.html +++ b/docs/advanced/deployment/cli.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ The command automates the manual deployment process and is the recommended way of deploying Wasp apps.

    Supported Providers​

    Wasp supports automated deployment to the following providers:

    • Fly.io - they offer 5$ free credit each month
    • Railway (coming soon, track it here #1157)

    Fly.io​

    Prerequisites​

    Fly provides free allowances for up to 3 VMs (so deploying a Wasp app to a new account is free), but all plans require you to add your credit card information before you can proceed. If you don't, the deployment will fail.

    You can add the required credit card information on the account's billing page.

    Fly.io CLI

    You will need the flyctl CLI installed on your machine before you can deploy to Fly.io.

    Deploying​

    Using the Wasp CLI, you can easily deploy a new app to Fly.io with just a single command:

    wasp deploy fly launch my-wasp-app mia
    Specifying Org

    If your account is a member of more than one organization on Fly.io, you will need to specify under which one you want to execute the command. To do that, provide an additional --org <org-slug> option. You can find out the names(slugs) of your organizations by running fly orgs list.

    Please do not CTRL-C or exit your terminal while the commands are running.

    Under the covers, this runs the equivalent of the following commands:

    wasp deploy fly setup my-wasp-app mia
    wasp deploy fly create-db mia
    wasp deploy fly deploy

    The commands above use the app basename my-wasp-app and deploy it to the Miami, Florida (US) region (called mia). Read more about Fly.io regions here.

    Unique Name

    Your app name must be unique across all of Fly or deployment will fail.

    The basename is used to create all three app tiers, resulting in three separate apps in your Fly dashboard:

    • my-wasp-app-client
    • my-wasp-app-server
    • my-wasp-app-db

    You'll notice that Wasp creates two new files in your project root directory:

    • fly-server.toml
    • fly-client.toml

    You should include these files in your version control so that you can deploy your app with a single command in the future.

    Using a Custom Domain For Your App​

    Setting up a custom domain is a three-step process:

    1. You need to add your domain to your Fly client app. You can do this by running:
    wasp deploy fly cmd --context client certs create mycoolapp.com
    Use Your Domain

    Make sure to replace mycoolapp.com with your domain in all of the commands mentioned in this section.

    This command will output the instructions to add the DNS records to your domain. It will look something like this:

    You can direct traffic to mycoolapp.com by:

    1: Adding an A record to your DNS service which reads

        A @ 66.241.1XX.154

    You can validate your ownership of mycoolapp.com by:

    2: Adding an AAAA record to your DNS service which reads:

        AAAA @ 2a09:82XX:1::1:ff40

    1. You need to add the DNS records for your domain:

      This will depend on your domain provider, but it should be a matter of adding an A record for @ and an AAAA record for @ with the values provided by the previous command.

    2. You need to set your domain as the WASP_WEB_CLIENT_URL environment variable for your server app:

    wasp deploy fly cmd --context server secrets set WASP_WEB_CLIENT_URL=https://mycoolapp.com

    We need to do this to keep our CORS configuration up to date.

    That's it, your app should be available at https://mycoolapp.com! 🎉

    Adding www Subdomain​

    If you'd like to also access your app at https://www.mycoolapp.com, you can generate certs for the www subdomain. 

    wasp deploy fly cmd --context client certs create www.mycoolapp.com

    Once you do that, you will need to add another DNS record for your domain. It should be a CNAME record for www with the value of your root domain. Here's an example:

    TypeNameValueTTL
    CNAMEwwwmycoolapp.com3600

    With the CNAME record (Canonical name), you are assigning the www subdomain as an alias to the root domain.

    Your app should now be available both at the root domain https://mycoolapp.com and the www sub-domain https://www.mycoolapp.com! 🎉

    API Reference​

    launch​

    launch is a convenience command that runs setup, create-db, and deploy in sequence.

    wasp deploy fly launch <app-name> <region>

    It accepts the following arguments:

    • <app-name> - the name of your app required

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    It gives you the same result as running the following commands:

    wasp deploy fly setup <app-name> <region>
    wasp deploy fly create-db <region>
    wasp deploy fly deploy

    Environment Variables​

    Server​

    If you are deploying an app that requires any other environment variables (like social auth secrets), you can set them with the --server-secret option:

    wasp deploy fly launch my-wasp-app mia --server-secret GOOGLE_CLIENT_ID=<...> --server-secret GOOGLE_CLIENT_SECRET=<...>
    Client​

    If you've added any client-side environment variables to your app, make sure to pass them to the terminal session before running the launch command, e.g.:

    REACT_APP_ANOTHER_VAR=somevalue wasp deploy fly launch my-wasp-app mia

    setup​

    setup will create your client and server apps on Fly, and add some secrets, but does not deploy them.

    wasp deploy fly setup <app-name> <region>

    It accepts the following arguments:

    • <app-name> - the name of your app required

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    After running setup, Wasp creates two new files in your project root directory: fly-server.toml and fly-client.toml. You should include these files in your version control.

    You can edit the fly-server.toml and fly-client.toml files to further configure your Fly deployments. Wasp will use the TOML files when you run deploy.

    If you want to maintain multiple apps, you can add the --fly-toml-dir <abs-path> option to point to different directories, like "dev" or "staging".

    Execute Only Once

    You should only run setup once per app. If you run it multiple times, it will create unnecessary apps on Fly.

    create-db​

    create-db will create a new database for your app.

    wasp deploy fly create-db <region>

    It accepts the following arguments:

    • <region> - the region where your app will be deployed required

      Read how to find the available regions here.

    Execute Only Once

    You should only run create-db once per app. If you run it multiple times, it will create multiple databases, but your app needs only one.

    deploy​

    wasp deploy fly deploy

    deploy pushes your client and server live.

    Run this command whenever you want to update your deployed app with the latest changes:

    wasp deploy fly deploy

    If you've added any client-side environment variables to your app, make sure to pass them to the terminal session before running the deploy command, e.g.:

    REACT_APP_ANOTHER_VAR=somevalue wasp deploy fly deploy

    Make sure to add your client-side environment variables every time you redeploy with the above command to ensure they are included in the build process!

    cmd​

    If want to run arbitrary Fly commands (e.g. flyctl secrets list for your server app), here's how to do it:

    wasp deploy fly cmd secrets list --context server

    Environment Variables​

    Server Secrets​

    If your app requires any other server-side environment variables (like social auth secrets), you can set them:

    1. initially in the launch command with the --server-secret option,
      or
    2. after the app has already been deployed by using the secrets set command:
    wasp deploy fly cmd secrets set GOOGLE_CLIENT_ID=<...> GOOGLE_CLIENT_SECRET=<...> --context=server

    Client Environment Variables​

    If you've added any client-side environment variables to your app, make sure to pass them to the terminal session before running a deployment command, e.g.:

    REACT_APP_ANOTHER_VAR=somevalue wasp deploy fly launch my-wasp-app mia

    or 

    REACT_APP_ANOTHER_VAR=somevalue wasp deploy fly deploy

    Fly.io Regions​

    Fly.io runs applications physically close to users: in datacenters around the world, on servers we run ourselves. You can currently deploy your apps in 34 regions, connected to a global Anycast network that makes sure your users hit our nearest server, whether they’re in Tokyo, São Paolo, or Frankfurt.

    Read more on Fly regions here.

    You can find the list of all available Fly regions by running:

    flyctl platform regions

    Multiple Fly.io Organizations​

    If you have multiple organizations, you can specify a --org option. For example:

    wasp deploy fly launch my-wasp-app mia --org hive

    Building Locally​

    Fly.io offers support for both locally built Docker containers and remotely built ones. However, for simplicity and reproducibility, the CLI defaults to the use of a remote Fly.io builder.

    If you want to build locally, supply the --build-locally option to wasp deploy fly launch or wasp deploy fly deploy.

    - - + + \ No newline at end of file diff --git a/docs/advanced/deployment/manually.html b/docs/advanced/deployment/manually.html index 61701fa8dc..56be84e4b8 100644 --- a/docs/advanced/deployment/manually.html +++ b/docs/advanced/deployment/manually.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -40,7 +40,7 @@ Set it to a random string at least 32 characters long (you can use an online generator).

  • PORT

    The server's HTTP port number. This is where the server listens for requests (default: 3001).

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

    Client Environment Variables

    Remember, if you have manually defined any other client-side environment variables in your project, make sure to add them to the command above when building your client

    The command above will build the web client and put it in the build/ directory in the .wasp/build/web-app/.

    This is also the moment to provide any additional env vars for the client code, next to REACT_APP_API_URL. Check the env vars docs for more details.

    Since the result of building is just a bunch of static files, you can now deploy your web client to any static hosting provider (e.g. Netlify, Cloudflare, ...) by deploying the contents of .wasp/build/web-app/build/.

    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, add a few more environment variables for the server code.

    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.

    Client Environment Variables

    Remember, if you have manually defined any other client-side environment variables in your project, make sure to add them to the command above when building your client

    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). https:// prefix is required!

      • add WASP_SERVER_URL - enter the server domain (e.g. https://server-production-XXXX.up.railway.app). https:// prefix is required!

      • 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 2cfb72ff78..2068f344c5 100644 --- a/docs/advanced/deployment/overview.html +++ b/docs/advanced/deployment/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ 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 a9112b8b74..290d7e2fab 100644 --- a/docs/advanced/email.html +++ b/docs/advanced/email.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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 Domains and create a new domain.
    3. Copy the domain and add it to your .env.server file.
    4. Create a new Sending API key under Send > Sending > Domain settings and find Sending API keys.
    5. Copy the API key and add it to your .env.server file.
    .env.server
    MAILGUN_API_KEY=
    MAILGUN_DOMAIN=

    Using the EU Region​

    If your domain region is in the EU, you need to set the MAILGUN_API_URL variable in your .env.server file:

    .env.server
    MAILGUN_API_URL=https://api.eu.mailgun.net

    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 668f76e3b0..8f1029e239 100644 --- a/docs/advanced/jobs.html +++ b/docs/advanced/jobs.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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 that your database provider is set to "postgresql" in your schema.prisma file. Read more about setting the provider here.

      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 617a279e69..67f761a43c 100644 --- a/docs/advanced/links.html +++ b/docs/advanced/links.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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>
      )
    }

    Catch-all Routes​

    If a route path ends with a /* pattern (also known as splat), you can use the Link component like this:

    main.wasp
    route CatchAllRoute { path: "/pages/*", to: CatchAllPage }
    page CatchAllPage { ... }
    TaskList.tsx
    <Link to="/pages/*" params={{ '*': 'about' }}>
      About
    </Link>

    This will result in a link like this: /pages/about.

    Optional Static Segments​

    If a route contains optional static segments, you'll need to specify one of the possible paths:

    main.wasp
    route OptionalRoute { path: "/task/:id/details?", to: OptionalPage }
    page OptionalPage { ... }
    TaskList.tsx
    /* You can include ... */
    <Link to="/task/:id/details" params={{ id: 1 }}>
      Task 1
    </Link>

    /* ... or exclude the optional segment */
    <Link to="/task/:id" params={{ id: 1 }}>
      Task 1
    </Link>

    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.

    Optional Static Segments​

    If a route contains optional static segments, you'll need to specify one of the possible paths:

    main.wasp
    route OptionalRoute { path: "/task/:id/details?", to: OptionalPage }
    page OptionalPage { ... }
    TaskList.tsx
    const linkToOptional = routes.OptionalRoute.build({
      path: '/task/:id/details', // or '/task/:id'
      params: { id: 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.

        In the case of optional static segments, you must provide one of the possible paths which include or exclude the optional segment. For example, if the path is /task/:id/details?, you must provide either /task/:id/details or /task/:id.

    • 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/:userId?"
      DetailRoute: {
        build: (
          options: {
            params: { id: ParamValue; userId?: ParamValue; },
            search?: string[][] | Record<string, string> | string | URLSearchParams
            hash?: string
          }
        ) => // ...
      },

      // OptionalRoute has a path like "/task/:id/details?"
      OptionalRoute: {
        build: (
          options: {
            path: '/task/:id/details' | '/task/:id',
            params: { id: ParamValue },
            search?: string[][] | Record<string, string> | string | URLSearchParams
            hash?: string
          }
        ) => // ...
      },

      // CatchAllRoute has a path like "/pages/*"
      CatchAllRoute: {
        build: (
          options: {
            params: { '*': 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 } })
    const linkToOptional = routes.DetailRoute.build({
      path: '/task/:id/details',
      params: { id: 1 },
    })
    const linkToCatchAll = routes.CatchAllRoute.build({
      params: { '*': 'about' },
    })
    - - + + \ No newline at end of file diff --git a/docs/advanced/middleware-config.html b/docs/advanced/middleware-config.html index 8dc9f228f4..dcc8ce49c2 100644 --- a/docs/advanced/middleware-config.html +++ b/docs/advanced/middleware-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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 ec3702241f..4517ec630a 100644 --- a/docs/advanced/web-sockets.html +++ b/docs/advanced/web-sockets.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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​

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

    The 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/auth-hooks.html b/docs/auth/auth-hooks.html index 7f113389e3..eea13a78f1 100644 --- a/docs/auth/auth-hooks.html +++ b/docs/auth/auth-hooks.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    Auth Hooks

    Auth hooks allow you to "hook into" the auth process at various stages and run your custom code. For example, if you want to forbid certain emails from signing up, or if you wish to send a welcome email to the user after they sign up, auth hooks are the way to go.

    Supported hooks​

    The following auth hooks are available in Wasp:

    We'll go through each of these hooks in detail. But first, let's see how the hooks fit into the auth flows:

    Signup Flow with Hooks
    Signup Flow with Hooks

    Login Flow with Hooks
    Login Flow with Hooks *

    * When using the OAuth auth providers, the login hooks are both called before the session is created but the session is created quickly afterward, so it shouldn't make any difference in practice.

    If you are using OAuth, the flow includes extra steps before the auth flow:

    OAuth Flow with Hooks
    OAuth Flow with Hooks

    Using hooks​

    To use auth hooks, you must first declare them in the Wasp file:

    app myApp {
      wasp: {
        version: "^0.15.0"
      },
      auth: {
        userEntity: User,
        methods: {
          ...
        },
        onBeforeSignup: import { onBeforeSignup } from "@src/auth/hooks",
        onAfterSignup: import { onAfterSignup } from "@src/auth/hooks",
        onBeforeOAuthRedirect: import { onBeforeOAuthRedirect } from "@src/auth/hooks",
        onBeforeLogin: import { onBeforeLogin } from "@src/auth/hooks",
        onAfterLogin: import { onAfterLogin } from "@src/auth/hooks",
      },
    }

    If the hooks are defined as async functions, Wasp awaits them. This means the auth process waits for the hooks to finish before continuing.

    Wasp ignores the hooks' return values. The only exception is the onBeforeOAuthRedirect hook, whose return value affects the OAuth redirect URL.

    We'll now go through each of the available hooks.

    Executing code before the user signs up​

    Wasp calls the onBeforeSignup hook before the user is created.

    The onBeforeSignup hook can be useful if you want to reject a user based on some criteria before they sign up.

    Works with Email Username & Password Discord Github Google Keycloak

    main.wasp
    app myApp {
      ...
      auth: {
        ...
        onBeforeSignup: import { onBeforeSignup } from "@src/auth/hooks",
      },
    }
    src/auth/hooks.js
    import { HttpError } from 'wasp/server'

    export const onBeforeSignup = async ({ providerId, prisma, req }) => {
      const count = await prisma.user.count()
      console.log('number of users before', count)
      console.log('provider name', providerId.providerName)
      console.log('provider user ID', providerId.providerUserId)

      if (count > 100) {
        throw new HttpError(403, 'Too many users')
      }

      if (
        providerId.providerName === 'email' &&
        providerId.providerUserId === 'some@email.com'
      ) {
        throw new HttpError(403, 'This email is not allowed')
      }
    }

    Read more about the data the onBeforeSignup hook receives in the API Reference.

    Executing code after the user signs up​

    Wasp calls the onAfterSignup hook after the user is created.

    The onAfterSignup hook can be useful if you want to send the user a welcome email or perform some other action after the user signs up like syncing the user with a third-party service.

    Since the onAfterSignup hook receives the OAuth tokens, you can use this hook to store the OAuth access token and/or refresh token in your database.

    Works with Email Username & Password Discord Github Google Keycloak

    main.wasp
    app myApp {
      ...
      auth: {
        ...
        onAfterSignup: import { onAfterSignup } from "@src/auth/hooks",
      },
    }
    src/auth/hooks.js
    export const onAfterSignup = async ({
      providerId,
      user,
      oauth,
      prisma,
      req,
    }) => {
      const count = await prisma.user.count()
      console.log('number of users after', count)
      console.log('user object', user)

      // If this is an OAuth signup, you have access to the OAuth tokens and the uniqueRequestId
      if (oauth) {
        console.log('accessToken', oauth.tokens.accessToken)
        console.log('uniqueRequestId', oauth.uniqueRequestId)

        const id = oauth.uniqueRequestId
        const data = someKindOfStore.get(id)
        if (data) {
          console.log('saved data for the ID', data)
        }
        someKindOfStore.delete(id)
      }
    }

    Read more about the data the onAfterSignup hook receives in the API Reference.

    Executing code before the OAuth redirect​

    Wasp calls the onBeforeOAuthRedirect hook after the OAuth redirect URL is generated but before redirecting the user. This hook can access the request object sent from the client at the start of the OAuth process.

    The onBeforeOAuthRedirect hook can be useful if you want to save some data (e.g. request query parameters) that you can use later in the OAuth flow. You can use the uniqueRequestId parameter to reference this data later in the onAfterSignup or onAfterLogin hooks.

    Works with Discord Github Google Keycloak

    main.wasp
    app myApp {
      ...
      auth: {
        ...
        onBeforeOAuthRedirect: import { onBeforeOAuthRedirect } from "@src/auth/hooks",
      },
    }
    src/auth/hooks.js
    export const onBeforeOAuthRedirect = async ({ url, oauth, prisma, req }) => {
      console.log('query params before oAuth redirect', req.query)

      // Saving query params for later use in onAfterSignup or onAfterLogin hooks
      const id = oauth.uniqueRequestId
      someKindOfStore.set(id, req.query)

      return { url }
    }

    This hook's return value must be an object that looks like this: { url: URL }. Wasp uses the URL to redirect the user to the OAuth provider.

    Read more about the data the onBeforeOAuthRedirect hook receives in the API Reference.

    Executing code before the user logs in​

    Wasp calls the onBeforeLogin hook before the user is logged in.

    The onBeforeLogin hook can be useful if you want to reject a user based on some criteria before they log in.

    Works with Email Username & Password Discord Github Google Keycloak

    main.wasp
    app myApp {
      ...
      auth: {
        ...
        onBeforeLogin: import { onBeforeLogin } from "@src/auth/hooks",
      },
    }
    src/auth/hooks.js
    import { HttpError } from 'wasp/server'

    export const onBeforeLogin = async ({ providerId, user, prisma, req }) => {
      if (
        providerId.providerName === 'email' &&
        providerId.providerUserId === 'some@email.com'
      ) {
        throw new HttpError(403, 'You cannot log in with this email')
      }
    }

    Read more about the data the onBeforeLogin hook receives in the API Reference.

    Executing code after the user logs in​

    Wasp calls the onAfterLogin hook after the user logs in.

    The onAfterLogin hook can be useful if you want to perform some action after the user logs in, like syncing the user with a third-party service.

    Since the onAfterLogin hook receives the OAuth tokens, you can use it to update the OAuth access token for the user in your database. You can also use it to refresh the OAuth access token if the provider supports it.

    Works with Email Username & Password Discord Github Google Keycloak

    main.wasp
    app myApp {
      ...
      auth: {
        ...
        onAfterLogin: import { onAfterLogin } from "@src/auth/hooks",
      },
    }
    src/auth/hooks.js
    export const onAfterLogin = async ({
      providerId,
      user,
      oauth,
      prisma,
      req,
    }) => {
      console.log('user object', user)

      // If this is an OAuth signup, you have access to the OAuth tokens and the uniqueRequestId
      if (oauth) {
        console.log('accessToken', oauth.tokens.accessToken)
        console.log('uniqueRequestId', oauth.uniqueRequestId)

        const id = oauth.uniqueRequestId
        const data = someKindOfStore.get(id)
        if (data) {
          console.log('saved data for the ID', data)
        }
        someKindOfStore.delete(id)
      }
    }

    Read more about the data the onAfterLogin hook receives in the API Reference.

    Refreshing the OAuth access token​

    Some OAuth providers support refreshing the access token when it expires. To refresh the access token, you need the OAuth refresh token.

    Wasp exposes the OAuth refresh token in the onAfterSignup and onAfterLogin hooks. You can store the refresh token in your database and use it to refresh the access token when it expires.

    Import the provider object with the OAuth client from the wasp/server/auth module. For example, to refresh the Google OAuth access token, import the google object from the wasp/server/auth module. You use the refreshAccessToken method of the OAuth client to refresh the access token.

    Here's an example of how you can refresh the access token for Google OAuth:

    src/auth/hooks.js
    import { google } from 'wasp/server/auth'

    export const onAfterLogin = async ({ oauth }) => {
      if (oauth.provider === 'google' && oauth.tokens.refreshToken !== null) {
        const newTokens = await google.oAuthClient.refreshAccessToken(
          oauth.tokens.refreshToken
        )
        log('new tokens', newTokens)
      }
    }

    Google exposes the accessTokenExpiresAt field in the oauth.tokens object. You can use this field to determine when the access token expires.

    If you want to refresh the token periodically, use a Wasp Job.

    API Reference​

    app myApp {
      wasp: {
        version: "^0.15.0"
      },
      auth: {
        userEntity: User,
        methods: {
          ...
        },
        onBeforeSignup: import { onBeforeSignup } from "@src/auth/hooks",
        onAfterSignup: import { onAfterSignup } from "@src/auth/hooks",
        onBeforeOAuthRedirect: import { onBeforeOAuthRedirect } from "@src/auth/hooks",
        onBeforeLogin: import { onBeforeLogin } from "@src/auth/hooks",
        onAfterLogin: import { onAfterLogin } from "@src/auth/hooks",
      },
    }

    Common hook input​

    The following properties are available in all auth hooks:

    • prisma: PrismaClient

      The Prisma client instance which you can use to query your database.

    • req: Request

      The Express request object from which you can access the request headers, cookies, etc.

    The onBeforeSignup hook​

    src/auth/hooks.js
    export const onBeforeSignup = async ({ providerId, prisma, req }) => {
      // Hook code goes here
    }

    The hook receives an object as input with the following properties:

    Wasp ignores this hook's return value.

    The onAfterSignup hook​

    src/auth/hooks.js
    export const onAfterSignup = async ({
      providerId,
      user,
      oauth,
      prisma,
      req,
    }) => {
      // Hook code goes here
    }

    The hook receives an object as input with the following properties:

    Wasp ignores this hook's return value.

    The onBeforeOAuthRedirect hook​

    src/auth/hooks.js
    export const onBeforeOAuthRedirect = async ({ url, oauth, prisma, req }) => {
      // Hook code goes here

      return { url }
    }

    The hook receives an object as input with the following properties:

    • url: URL

      Wasp uses the URL for the OAuth redirect.

    • oauth: { uniqueRequestId: string }

      The oauth object has the following fields:

      • uniqueRequestId: string

        The unique request ID for the OAuth flow (you might know it as the state parameter in OAuth.)

        You can use the unique request ID to save data (e.g. request query params) that you can later use in the onAfterSignup or onAfterLogin hooks.

    • Plus the common hook input

    This hook's return value must be an object that looks like this: { url: URL }. Wasp uses the URL to redirect the user to the OAuth provider.

    The onBeforeLogin hook​

    src/auth/hooks.js
    export const onBeforeLogin = async ({ providerId, prisma, req }) => {
      // Hook code goes here
    }

    The hook receives an object as input with the following properties:

    Wasp ignores this hook's return value.

    The onAfterLogin hook​

    src/auth/hooks.js
    export const onAfterLogin = async ({
      providerId,
      user,
      oauth,
      prisma,
      req,
    }) => {
      // Hook code goes here
    }

    The hook receives an object as input with the following properties:

    Wasp ignores this hook's return value.

    ProviderId fields​

    The providerId object represents the user for the current authentication method. Wasp passes it to the onBeforeSignup, onAfterSignup, onBeforeLogin, and onAfterLogin hooks.

    It has the following fields:

    • providerName: string

      The provider's name (e.g. 'email', 'google', 'github)

    • providerUserId: string

      The user's unique ID in the provider's system (e.g. email, Google ID, GitHub ID)

    OAuth fields​

    Wasp passes the oauth object to the onAfterSignup and onAfterLogin hooks only when the user is authenticated with Social Auth.

    It has the following fields:

    • providerName: string

      The name of the OAuth provider the user authenticated with (e.g. 'google', 'github').

    • tokens: Tokens

      You can use the OAuth tokens to make requests to the provider's API on the user's behalf.

      Depending on the OAuth provider, the tokens object might have different fields. For example, Google has the fields accessToken, refreshToken, idToken, and accessTokenExpiresAt.

    • uniqueRequestId: string

      The unique request ID for the OAuth flow (you might know it as the state parameter in OAuth.)

      You can use the unique request ID to get the data that was saved in the onBeforeOAuthRedirect hook.

    - - + + \ No newline at end of file diff --git a/docs/auth/email.html b/docs/auth/email.html index e26b4dca0e..40326a3614 100644 --- a/docs/auth/email.html +++ b/docs/auth/email.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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 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.15.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:

    schema.prisma
    // 5. Define the user entity
    model User {
      id Int @id @default(autoincrement())
      // Add your own fields below
      // ...
    }

    You can read more about how the User is connected to the rest of the auth system and how you can access the user data in the Accessing User Data 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
    // ...

    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="h-full w-full bg-white">
          <div className="flex min-h-[75vh] min-w-full items-center justify-center">
            <div className="h-full w-full max-w-sm bg-white p-5">
              <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.

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

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

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

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

    When you receive the user object on the client or the server, you'll be able to access the user's email and other information like this:

    const emailIdentity = user.identities.email

    // Email address the the user used to sign up, e.g. "fluffyllama@app.com".
    emailIdentity.id

    // `true` if the user has verified their email address.
    emailIdentity.isEmailVerified

    // Datetime when the email verification email was sent.
    emailIdentity.emailVerificationSentAt

    // Datetime when the last password reset email was sent.
    emailIdentity.passwordResetSentAt

    Read more about accessing the user data in the Accessing User Data section of the docs.

    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"
      },
      // ...
    }
    schema.prisma
    model User {
      id Int @id @default(autoincrement())
    }

    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.

    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 f091a0f994..425a4a760e 100644 --- a/docs/auth/entities.html +++ b/docs/auth/entities.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    Accessing User Data

    First, we'll check out the most practical info: how to access the user's data in your app.

    Then, we'll dive into the details of the auth entities that Wasp creates behind the scenes to store the user's data. For auth each method, Wasp needs to store different information about the user. For example, username for Username & password auth, email verification status for Email auth, and so on.

    We'll also show you how you can use these entities to create a custom signup action.

    Accessing the Auth Fields​

    When you receive the user object on the client or the server, it will contain all the user fields you defined in the User entity in the schema.prisma file. In addition to that, it will also contain all the auth-related fields that Wasp stores. This includes things like the username or the email verification status. In Wasp, this data is called the AuthUser object.

    AuthUser Object Fields​

    All the User fields you defined will be present at the top level of the AuthUser object. The auth-related fields will be on the identities object. For each auth method you enable, there will be a separate data object in the identities object.

    The AuthUser object will change depending on which auth method you have enabled in the Wasp file. For example, if you enabled the email auth and Google auth, it would look something like this:

    If the user has only the Google identity, the AuthUser object will look like this:

    const user = {
      // User data
      id: 'cluqs9qyh00007cn73apj4hp7',
      address: 'Some address',

      // Auth methods specific data
      identities: {
        email: null,
        google: {
          id: '1117XXXX1301972049448',
        },
      },
    }

    In the examples above, you can see the identities object contains the email and google objects. The email object contains the email-related data and the google object contains the Google-related data.

    Make sure to check if the data exists

    Before accessing some auth method's data, you'll need to check if that data exists for the user and then access it:

    if (user.identities.google !== null) {
      const userId = user.identities.google.id
      // ...
    }

    You need to do this because if a user didn't sign up with some auth method, the data for that auth method will be null.

    Let's look at the data for each of the available auth methods:

    • Username & password data

      const usernameIdentity = user.identities.username

      // Username that the user used to sign up, e.g. "fluffyllama"
      usernameIdentity.id

    • Email data

      const emailIdentity = user.identities.email

      // Email address the the user used to sign up, e.g. "fluffyllama@app.com".
      emailIdentity.id

      // `true` if the user has verified their email address.
      emailIdentity.isEmailVerified

      // Datetime when the email verification email was sent.
      emailIdentity.emailVerificationSentAt

      // Datetime when the last password reset email was sent.
      emailIdentity.passwordResetSentAt

    • Google data

      const googleIdentity = user.identities.google

      // Google User ID for example "123456789012345678901"
      googleIdentity.id

    • GitHub data

      const githubIdentity = user.identities.github

      // GitHub User ID for example "12345678"
      githubIdentity.id

    • Keycloak data

      const keycloakIdentity = user.identities.keycloak

      // Keycloak User ID for example "12345678-1234-1234-1234-123456789012"
      keycloakIdentity.id

    • Discord data

      const discordIdentity = user.identities.discord

      // Discord User ID for example "80351110224678912"
      discordIdentity.id

    If you support multiple auth methods, you'll need to find which identity exists for the user and then access its data:

    if (user.identities.email !== null) {
      const email = user.identities.email.id
      // ...
    } else if (user.identities.google !== null) {
      const googleId = user.identities.google.id
      // ...
    }

    getFirstProviderUserId Helper​

    The getFirstProviderUserId method returns the first user ID that it finds for the user. For example if the user has signed up with email, it will return the email. If the user has signed up with Google, it will return the Google ID.

    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
    const MainPage = ({ user }) => {
      const userId = user.getFirstProviderUserId()
      // ...
    }
    src/tasks.js
    export const createTask = async (args, context) => {
      const userId = context.user.getFirstProviderUserId()
      // ...
    }

    * Multiple identities per user will be possible in the future and then the getFirstProviderUserId method will return the ID of the first identity that it finds without any guarantees about which one it will be.

    Including the User with Other Entities​

    Sometimes, you might want to include the user's data when fetching other entities. For example, you might want to include the user's data with the tasks they have created.

    We'll mention the auth and the identities relations which we will explain in more detail later in the Entities Explained section.

    Be careful about sensitive data

    You'll need to include the auth and the identities relations to get the full auth data about the user. However, you should keep in mind that the providerData field in the identities can contain sensitive data like the user's hashed password (in case of email or username auth), so you will likely want to exclude it if you are returning those values to the client.

    You can include the full user's data with other entities using the include option in the Prisma queries:

    src/tasks.js
    export const getAllTasks = async (args, context) => {
      return context.entities.Task.findMany({
        orderBy: { id: 'desc' },
        select: {
          id: true,
          title: true,
          user: {
            include: {
              auth: {
                include: {
                  identities: {
                    // Including only the `providerName` and `providerUserId` fields
                    select: {
                      providerName: true,
                      providerUserId: true,
                    },
                  },
                },
              },
            },
          },
        },
      })
    }

    If you have some piece of the auth data that you want to access frequently (for example the username), it's best to store it at the top level of the User entity.

    For example, save the username or email as a property on the User and you'll be able to access it without including the auth and identities fields. We show an example in the Defining Extra Fields on the User Entity section of the docs.

    Getting Auth Data from the User Object​

    When you have the user object with the auth and identities fields, it can be a bit tedious to obtain the auth data (like username or Google ID) from it:

    src/MainPage.jsx
    function MainPage() {
      // ...
      return (
        <div className="tasks">
          {tasks.map((task) => (
            <div key={task.id} className="task">
              {task.title} by {task.user.auth?.identities[0].providerUserId}
            </div>
          ))}
        </div>
      )
    }

    Wasp offers a few helper methods to access the user's auth data when you retrieve the user like this. They are getUsername, getEmail and getFirstProviderUserId. They can be used both on the client and the server.

    getUsername​

    It accepts the user object and if the user signed up with the Username & password auth method, it returns the username or null otherwise. The user object needs to have the auth and the identities relations included.

    src/MainPage.jsx
    import { getUsername } from 'wasp/auth'

    function MainPage() {
      // ...
      return (
        <div className="tasks">
          {tasks.map((task) => (
            <div key={task.id} className="task">
              {task.title} by {getUsername(task.user)}
            </div>
          ))}
        </div>
      )
    }

    getEmail​

    It accepts the user object and if the user signed up with the Email auth method, it returns the email or null otherwise. The user object needs to have the auth and the identities relations included.

    src/MainPage.jsx
    import { getEmail } from 'wasp/auth'

    function MainPage() {
      // ...
      return (
        <div className="tasks">
          {tasks.map((task) => (
            <div key={task.id} className="task">
              {task.title} by {getEmail(task.user)}
            </div>
          ))}
        </div>
      )
    }

    getFirstProviderUserId​

    It returns the first user ID that it finds for the user. For example if the user has signed up with email, it will return the email. If the user has signed up with Google, it will return the Google ID. The user object needs to have the auth and the identities relations included.

    src/MainPage.jsx
    import { getFirstProviderUserId } from 'wasp/auth'

    function MainPage() {
      // ...
      return (
        <div className="tasks">
          {tasks.map((task) => (
            <div key={task.id} className="task">
              {task.title} by {getFirstProviderUserId(task.user)}
            </div>
          ))}
        </div>
      )
    }

    Entities Explained​

    To store user's auth information, Wasp does a few things behind the scenes. Wasp takes your schema.prisma file and combines it with additional entities to create the final schema.prisma file that is used in your app.

    In this section, we will explain which entities are created and how they are connected.

    User Entity​

    When you want to add authentication to your app, you need to specify the userEntity field.

    For example, you might set it to User:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.15.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        // ...
      },
    }

    And define the User in the schema.prisma file:

    schema.prisma
    model User {
      id Int @id @default(autoincrement())
      // Any other fields you want to store about the user
    }

    The User 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.

    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.

    model Auth {
      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[]
    }

    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.

    model AuthIdentity {
      providerName   String
      providerUserId String
      providerData   String @default("{}")
      authId         String
      auth           Auth   @relation(fields: [authId], references: [id], onDelete: Cascade)

      @@id([providerName, providerUserId])
    }

    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.

    model Session {
      id        String   @id @unique
      expiresAt DateTime
      userId    String
      auth      Auth     @relation(references: [id], fields: [userId], onDelete: Cascade)

      @@index([userId])
    }

    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.

    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 ed1d9aa65e..9f50a0df73 100644 --- a/docs/auth/overview.html +++ b/docs/auth/overview.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.15.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

    Discord »

    Users sign in with their Discord 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. In addition to that, it will also contain all the auth-related fields that Wasp stores. This includes things like the username or the email verification status. For example, if you have a user that signed up using an email and password, the user object might look like this:

    const user = {
      // User data
      id: "cluqsex9500017cn7i2hwsg17",
      address: "Some address",

      // Auth methods specific data
      identities: {
        email: {
          id: "user@app.com",
          isEmailVerified: true,
          emailVerificationSentAt: "2024-04-08T10:06:02.204Z",
          passwordResetSentAt: null,
        },
      },
    }

    You can read more about how the User is connected to the rest of the auth system and how you can access the user data in the Accessing User Data 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",
      },
    }
    schema.prisma
    model User {
      id      Int     @id @default(autoincrement())
      address String?
    }

    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 you defined in the schema.prisma file.

    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",
      }
    }

    //...

    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 is connected to the rest of the auth system and how you can access the user data in the Accessing User Data 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

    Discord »

    Users sign in with their Discord 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 essential 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 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/discord.html b/docs/auth/social-auth/discord.html index 0893d31813..c22d042035 100644 --- a/docs/auth/social-auth/discord.html +++ b/docs/auth/social-auth/discord.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.15.0

    Discord

    Wasp supports Discord Authentication out of the box.

    Letting your users log in using their Discord accounts turns the signup process into a breeze.

    Let's walk through enabling Discord Authentication, explain some of the default settings, and show how to override them.

    Setting up Discord Auth​

    Enabling Discord Authentication comes down to a series of steps:

    1. Enabling Discord authentication in the Wasp file.
    2. Adding the User entity.
    3. Creating a Discord 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 routes and pages
    route LoginRoute { ... }
    page LoginPage { ... }

    1. Adding Discord Auth to Your Wasp File​

    Let's start by properly configuring the Auth object:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.15.0"
      },
      title: "My App",
      auth: {
        // 1. Specify the User entity  (we'll define it next)
        userEntity: User,
        methods: {
          // 2. Enable Discord Auth
          discord: {}
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    2. Add the User Entity​

    Let's now define the app.auth.userEntity entity in the schema.prisma file:

    schema.prisma
    // 3. Define the user entity
    model User {
      id Int @id @default(autoincrement())
      // Add your own fields below
      // ...
    }

    3. Creating a Discord App​

    To use Discord as an authentication method, you'll first need to create a Discord App and provide Wasp with your client key and secret. Here's how you do it:

    1. Log into your Discord account and navigate to: https://discord.com/developers/applications.
    2. Select New Application.
    3. Supply required information.
    Discord Applications Screenshot
    1. Go to the OAuth2 tab on the sidebar and click Add Redirect
    • For development, put: http://localhost:3001/auth/discord/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/discord/callback.
    1. Hit Save Changes.
    2. Hit Reset Secret.
    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
    DISCORD_CLIENT_ID=your-discord-client-id
    DISCORD_CLIENT_SECRET=your-discord-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
    // ...

    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="h-full w-full bg-white">
          <div className="flex min-h-[75vh] min-w-full items-center justify-center">
            <div className="h-full w-full max-w-sm bg-white p-5">
              <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 Discord Auth! 🎉

    Discord 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 discord: {} to the auth.methods dictionary to use it with default settings.

    main.wasp
    app myApp {
      wasp: {
        version: "^0.15.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          discord: {}
        },
        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 Discord​

    We are using Discord's API and its /users/@me endpoint to get the user data.

    The data we receive from Discord on the /users/@me endpoint looks something like this:

    {
      "id": "80351110224678912",
      "username": "Nelly",
      "discriminator": "1337",
      "avatar": "8342729096ea3675442027381ff50dfe",
      "verified": true,
      "flags": 64,
      "banner": "06c16474723fe537c283b8efa61a30c8",
      "accent_color": 16711680,
      "premium_type": 1,
      "public_flags": 64,
      "avatar_decoration_data": {
        "sku_id": "1144058844004233369",
        "asset": "a_fed43ab12698df65902ba06727e20c0e"
      }
    }

    The fields you receive will depend on the scopes you requested. The default scope is set to identify only. If you want to get the email, you need to specify the email scope in the configFn function.

    For an up to date info about the data received from Discord, please refer to the Discord API documentation.

    Using the Data Received From Discord​

    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.15.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          discord: {
            configFn: import { getConfig } from "@src/auth/discord.js",
            userSignupFields: import { userSignupFields } from "@src/auth/discord.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }
    schema.prisma
    model User {
      id          Int    @id @default(autoincrement())
      username    String @unique
      displayName String
    }

    // ...
    src/auth/discord.js
    export const userSignupFields = {
      username: (data) => data.profile.global_name,
      avatarUrl: (data) => data.profile.avatar,
    }

    export function getConfig() {
      return {
        scopes: ['identify'],
      }
    }

    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.

    When you receive the user object on the client or the server, you'll be able to access the user's Discord ID like this:

    const discordIdentity = user.identities.discord

    // Discord User ID for example "80351110224678912"
    discordIdentity.id

    Read more about accessing the user data in the Accessing User Data section of the docs.

    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.15.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          discord: {
            configFn: import { getConfig } from "@src/auth/discord.js",
            userSignupFields: import { userSignupFields } from "@src/auth/discord.js"
          }
        },
        onAuthFailedRedirectTo: "/login"
      },
    }

    The discord dict has the following properties:

    • configFn: ExtImport​

      This function should return an object with the scopes for the OAuth provider.

      src/auth/discord.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/github.html b/docs/auth/social-auth/github.html index 817d75fb8f..2b6ce1146e 100644 --- a/docs/auth/social-auth/github.html +++ b/docs/auth/social-auth/github.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ 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 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.15.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 in the schema.prisma file:

    schema.prisma
    // 3. Define the user entity
    model User {
      id Int @id @default(autoincrement())
      // Add your own fields below
      // ...
    }

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

    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="h-full w-full bg-white">
          <div className="flex min-h-[75vh] min-w-full items-center justify-center">
            <div className="h-full w-full max-w-sm bg-white p-5">
              <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.15.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.15.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"
      },
    }
    schema.prisma
    model User {
      id          Int    @id @default(autoincrement())
      username    String @unique
      displayName String
    }

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

    When you receive the user object on the client or the server, you'll be able to access the user's GitHub ID like this:

    const githubIdentity = user.identities.github

    // GitHub User ID for example "12345678"
    githubIdentity.id

    Read more about accessing the user data in the Accessing User Data section of the docs.

    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.15.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 c23ba757fa..84033c1bd2 100644 --- a/docs/auth/social-auth/google.html +++ b/docs/auth/social-auth/google.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ 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="h-full w-full bg-white">
          <div className="flex min-h-[75vh] min-w-full items-center justify-center">
            <div className="h-full w-full max-w-sm bg-white p-5">
              <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.15.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.15.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"
      },
    }
    schema.prisma
    model User {
      id          Int    @id @default(autoincrement())
      username    String @unique
      displayName String
    }

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

    When you receive the user object on the client or the server, you'll be able to access the user's Google ID like this:

    const googleIdentity = user.identities.google

    // Google User ID for example "123456789012345678901"
    googleIdentity.id

    Read more about accessing the user data in the Accessing User Data section of the docs.

    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.15.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 de4c8b54bf..23116317ec 100644 --- a/docs/auth/social-auth/keycloak.html +++ b/docs/auth/social-auth/keycloak.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ 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="h-full w-full bg-white">
          <div className="flex min-h-[75vh] min-w-full items-center justify-center">
            <div className="h-full w-full max-w-sm bg-white p-5">
              <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.15.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.15.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"
      },
    }
    schema.prisma
    model User {
      id          Int    @id @default(autoincrement())
      username    String @unique
      displayName String
    }

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

    When you receive the user object on the client or the server, you'll be able to access the user's Keycloak ID like this:

    const keycloakIdentity = user.identities.keycloak

    // Keycloak User ID for example "12345678-1234-1234-1234-123456789012"
    keycloakIdentity.id

    Read more about accessing the user data in the Accessing User Data section of the docs.

    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.15.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 7e68a872eb..4b3cfc10f0 100644 --- a/docs/auth/social-auth/overview.html +++ b/docs/auth/social-auth/overview.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -31,7 +31,7 @@ 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 { Navigate } from 'react-router-dom'

    export function HomePage() {
      const { data: user } = useAuth()

      if (user.isSignupComplete === false) {
        return <Navigate 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 aa6c5e7615..3aff2d2d75 100644 --- a/docs/auth/ui.html +++ b/docs/auth/ui.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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, Keycloak, and Discord 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, Keycloak, and Discord 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 150f94c0a9..3d055d63f5 100644 --- a/docs/auth/username-and-pass.html +++ b/docs/auth/username-and-pass.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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 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.15.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:

    schema.prisma
    // 3. Define the user entity
    model User {
      id Int @id @default(autoincrement())
      // Add your own fields below
      // ...
    }

    You can read more about how the User is connected to the rest of the auth system and how you can access the user data in the Accessing User Data 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
    // ...
    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="h-full w-full bg-white">
          <div className="flex min-h-[75vh] min-w-full items-center justify-center">
            <div className="h-full w-full max-w-sm bg-white p-5">
              <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 { useNavigate, Link } from 'react-router-dom'

    export function LoginPage() {
      const [username, setUsername] = useState('')
      const [password, setPassword] = useState('')
      const [error, setError] = useState(null)
      const navigate = useNavigate()

      async function handleSubmit(event) {
        event.preventDefault()
        try {
          await login(username, password)
          navigate('/')
        } 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 { useNavigate, Link } from 'react-router-dom'

    export function Signup() {
      const [username, setUsername] = useState('')
      const [password, setPassword] = useState('')
      const [error, setError] = useState(null)
      const navigate = useNavigate()

      async function handleSubmit(event) {
        event.preventDefault()
        try {
          await signup({
            username,
            password,
          })
          await login(username, password)
          navigate('/')
        } 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.

    When you receive the user object on the client or the server, you'll be able to access the user's username like this:

    const usernameIdentity = user.identities.username

    // Username that the user used to sign up, e.g. "fluffyllama"
    usernameIdentity.id

    Read more about accessing the user data in the Accessing User Data section of the docs.

    API Reference​

    userEntity fields​

    main.wasp
    app myApp {
      wasp: {
        version: "^0.15.0"
      },
      title: "My App",
      auth: {
        userEntity: User,
        methods: {
          usernameAndPassword: {},
        },
        onAuthFailedRedirectTo: "/login"
      }
    }
    schema.prisma
    model User {
      id Int @id @default(autoincrement())
    }

    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.15.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 e7b3e89abe..92d1527df0 100644 --- a/docs/contact.html +++ b/docs/contact.html @@ -18,14 +18,14 @@ - - - + + +
    - - + + \ No newline at end of file diff --git a/docs/contributing.html b/docs/contributing.html index 3b7d19b06e..015f868dd1 100644 --- a/docs/contributing.html +++ b/docs/contributing.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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 faab6333be..acb1bd0164 100644 --- a/docs/data-model/backends.html +++ b/docs/data-model/backends.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -34,7 +34,7 @@ Wasp defines DbSeedFn like this:

    type DbSeedFn = (prisma: PrismaClient) => Promise<void>

    Annotating the function devSeedSimple with this type tells TypeScript:

    • The seeding function's argument (prisma) is of type PrismaClient.
    • The seeding function's return value is Promise<void>.

    Running seed functions​

    Run the command wasp db seed and Wasp will ask you which seed function you'd like to run (if you've defined more than one).

    Alternatively, run the command wasp db seed <seed-name> to choose a specific seed function right away, for example:

    wasp db seed devSeedSimple

    Check the API Reference for more details on these commands.

    tip

    You'll often want to call wasp db seed right after you run wasp db reset, as it makes sense to fill the database with initial data after clearing it.

    API Reference​

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      db: {
        seeds: [
          import devSeed from "@src/dbSeeds.js"
        ],
      }
    }

    app.db is a dictionary with the following fields (all fields are optional):

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

    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 19c947c481..673a078ebb 100644 --- a/docs/data-model/crud.html +++ b/docs/data-model/crud.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -29,7 +29,7 @@ Read more about the default implementations here.

    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,
            },
          },
        },
      })
    }

    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 works on top of an 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 fa5ba9992e..e7974de241 100644 --- a/docs/data-model/entities.html +++ b/docs/data-model/entities.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.15.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. This means that you use the schema.prisma file to define your database models and relationships. Wasp understands the Prisma schema file and picks up all the models you define there. You can read more about this in the Prisma Schema File section of the docs.

    In your project, you'll find a schema.prisma file in the root directory:

    .
    ├── main.wasp
    ...
    ├── schema.prisma
    ├── src
    ├── tsconfig.json
    └── vite.config.ts

    Prisma uses the Prisma Schema Language, a simple definition language explicitly created for defining models. 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​

    A Prisma model declaration in the schema.prisma file represents a Wasp Entity.

    Entity vs Model

    You might wonder why we distinguish between a Wasp Entity and a Prisma model if they're essentially the same thing right now.

    While defining a Prisma model is currently the only way to create an Entity in Wasp, the Entity concept is a higher-level abstraction. We plan to expand on Entities in the future, both in terms of how you can define them and what you can do with them.

    So, think of an Entity as a Wasp concept and a model as a Prisma concept. For now, all Prisma models are Entities and vice versa, but this relationship might evolve as Wasp grows.

    Here's how you could define an Entity that represents a Task:

    schema.prisma
    model Task {
      id          String  @id @default(uuid())
      description String
      isDone      Boolean @default(false)
    }

    The above Prisma model 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 - A string value serving as a primary key. The database automatically generates it by generating a random unique 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 the schema.prisma file.
    2. Run wasp db migrate-dev. This command syncs the database model with the Entity definitions the schema.prisma 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 703941ad99..1e1fa7dc19 100644 --- a/docs/data-model/operations/actions.html +++ b/docs/data-model/operations/actions.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -47,7 +47,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 (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 (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 (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 25e7fbd3fc..3c9aa2a693 100644 --- a/docs/data-model/operations/overview.html +++ b/docs/data-model/operations/overview.html @@ -18,15 +18,15 @@ - - - + + +
    - - + + \ No newline at end of file diff --git a/docs/data-model/operations/queries.html b/docs/data-model/operations/queries.html index 6cbc1b7781..4089a44020 100644 --- a/docs/data-model/operations/queries.html +++ b/docs/data-model/operations/queries.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -50,7 +50,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/data-model/prisma-file.html b/docs/data-model/prisma-file.html index ffafbca291..bdd2d1999b 100644 --- a/docs/data-model/prisma-file.html +++ b/docs/data-model/prisma-file.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    Prisma Schema File

    Wasp uses Prisma to interact with the database. Prisma is a "Next-generation Node.js and TypeScript ORM" that provides a type-safe API for working with your database.

    With Prisma, you define your application's data model in a schema.prisma file. Read more about how Wasp Entities relate to Prisma models on the Entities page.

    In Wasp, the schema.prisma file is located in your project's root directory:

    .
    ├── main.wasp
    ...
    ├── schema.prisma
    ├── src
    ├── tsconfig.json
    └── vite.config.ts

    Wasp uses the schema.prisma file to understand your app's data model and generate the necessary code to interact with the database.

    Wasp file and Prisma schema file​

    Let's see how Wasp and Prisma files work together to define your application.

    Here's an example schema.prisma file where we defined some database options and two models (User and Task) with a one-to-many relationship:

    schema.prisma
    datasource db {
      provider = "postgresql"
      url      = env("DATABASE_URL")
    }

    generator client {
      provider = "prisma-client-js"
    }

    model User {
      id      Int        @id @default(autoincrement())
      tasks   Task[]
    }

    model Task {
      id          Int        @id @default(autoincrement())
      description String
      isDone      Boolean    @default(false)
      user        User       @relation(fields: [userId], references: [id])
      userId      Int
    }

    Wasp reads this schema.prisma file and extracts the info about your database models and database config.

    The datasource block defines which database you want to use (PostgreSQL in this case) and some other options.

    The generator block defines how to generate the Prisma Client code that you can use in your application to interact with the database.

    Relationship between Wasp file and Prisma file
    Relationship between Wasp file and Prisma file

    Finally, Prisma models become Wasp Entities which can be then used in the main.wasp file:

    main.wasp
    app myApp {
      wasp: {
        version: "^0.15.0"
      },
      title: "My App",
    }

    ...

    // Using Wasp Entities in the Wasp file

    query getTasks {
      fn: import { getTasks } from "@src/queries",
      entities: [Task]
    }

    job myJob {
      executor: PgBoss,
      perform: {
        fn: import { foo } from "@src/workers/bar"
      },
      entities: [Task],
    }

    api fooBar {
      fn: import { fooBar } from "@src/apis",
      entities: [Task],
      httpRoute: (GET, "/foo/bar/:email")
    }

    In the implementation of the getTasks query, Task is a Wasp Entity that corresponds to the Task model defined in the schema.prisma file.

    The same goes for the myJob job and fooBar API, where Task is used as an Entity.

    To learn more about the relationship between Wasp Entities and Prisma models, check out the Entities page.

    Wasp-specific Prisma configuration​

    Wasp mostly lets you use the Prisma schema file as you would in any other JS/TS project. However, there are some Wasp-specific rules you need to follow.

    The datasource block​

    schema.prisma
    datasource db {
      provider = "postgresql"
      url      = env("DATABASE_URL")
    }

    Wasp takes the datasource you write and use it as-is.

    There are some rules you need to follow:

    • You can only use "postgresql" or "sqlite" as the provider because Wasp only supports PostgreSQL and SQLite databases for now.
    • You must set the url field to env("DATABASE_URL") so that Wasp can work properly with your database.

    The generator blocks​

    schema.prisma
    generator client {
      provider = "prisma-client-js"
    }

    Wasp requires that there is a generator block with provider = "prisma-client-js" in the schema.prisma file.

    You can add additional generators if you need them in your project.

    The model blocks​

    schema.prisma
    model User {
      id      Int        @id @default(autoincrement())
      tasks   Task[]
    }

    model Task {
      id          Int        @id @default(autoincrement())
      description String
      isDone      Boolean    @default(false)
      user        User       @relation(fields: [userId], references: [id])
      userId      Int
    }

    You can define your models in any way you like, if it's valid Prisma schema code, it will work with Wasp.

    Triple slash comments

    Wasp doesn't yet fully support /// comment syntax in the schema.prisma file. We are tracking it here, let us know if this is something you need.

    Prisma preview features​

    Prisma is still in active development and some of its features are not yet stable. To enable various preview features in Prisma, you need to add the previewFeatures field to the generator block in the schema.prisma file.

    For example, one useful Prisma preview feature is PostgreSQL extensions support, which allows you to use PostgreSQL extensions like pg_vector or pg_trgm in your database schema:

    schema.prisma
    datasource db {
      provider   = "postgresql"
      url        = env("DATABASE_URL")
      extensions = [pgvector(map: "vector")]
    }

    generator client {
      provider        = "prisma-client-js"
      previewFeatures = ["postgresqlExtensions"]
    }

    // ...

    Read more about preview features in the Prisma docs here or about using PostgreSQL extensions here.

    - - + + \ No newline at end of file diff --git a/docs/editor-setup.html b/docs/editor-setup.html index 8017f9ef4e..b6d2ebafb4 100644 --- a/docs/editor-setup.html +++ b/docs/editor-setup.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.15.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
    • the Prisma extension for .prisma files
    • scaffolding of new project files
    • code completion
    • diagnostics (errors and warnings)
    • go to definition

    and more!

    LSP Problems

    If you are using TypeScript, your editor may sometimes report type and import errors even while wasp start is running.

    This happens when the TypeScript Language Server gets out of sync with the current code. If you're using VS Code, you can manually restart the language server by opening the command palette and selecting "TypeScript: Restart TS Server." Open the command pallete with:

    • Ctrl + Shift + P if you're on Windows or Linux.
    • Cmd + Shift + P if you're on a Mac.
    - - + + \ No newline at end of file diff --git a/docs/general/cli.html b/docs/general/cli.html index 82fc23cb59..5c591be1fa 100644 --- a/docs/general/cli.html +++ b/docs/general/cli.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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.

    using prisma CLI directly

    Although Wasp uses the schema.prisma file to define the database schema, you must not use the prisma command directly. Instead, use the wasp db commands.

    Wasp adds some additional functionality on top of Prisma, and using prisma commands directly can lead to unexpected behavior e.g. missing auth models, incorrect database setup, etc.

    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.14.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 bf5f0ba6d9..f00263636f 100644 --- a/docs/general/language.html +++ b/docs/general/language.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.15.0

    Wasp Language (.wasp)

    Wasp language (what you write in .wasp files) is a declarative, statically typed, domain-specific language (DSL).

    Wasp TS config [Early-preview feature]

    If you wish, you can alternatively define your Wasp config in TS (main.wasp.ts) instead of main.wasp.

    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=})
      • 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
        • job
        • page
        • query
        • route
        • crud
      • Enum types
        • DbSystem
        • HttpMethod
        • JobExecutor
        • EmailProvider
      • Models from the schema.prisma file
        • You can reference models defined in the schema.prisma file in your Wasp file by using the model name e.g. Task.

    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/general/typescript.html b/docs/general/typescript.html index c66dd19754..c3b5732de7 100644 --- a/docs/general/typescript.html +++ b/docs/general/typescript.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -33,7 +33,7 @@ support when implementing the Query. Thanks to this type, the compiler knows:

    • The type of the context object.
    • The type of args.
    • The Query's return type.

    And gives you Intellisense and type-checking. Read more about this feature here.

    You don't need to change anything inside the .wasp file.

    Migrating the rest of the project​

    You can migrate your project gradually - on a file-by-file basis.

    When you want to migrate a file, follow the procedure outlined above:

    1. Change the file's extension.
    2. Fix the type errors.
    3. Read the Wasp docs and decide which TypeScript features you want to use.
    LSP Problems

    If you are using TypeScript, your editor may sometimes report type and import errors even while wasp start is running.

    This happens when the TypeScript Language Server gets out of sync with the current code. If you're using VS Code, you can manually restart the language server by opening the command palette and selecting "TypeScript: Restart TS Server." Open the command pallete with:

    • Ctrl + Shift + P if you're on Windows or Linux.
    • Cmd + Shift + P if you're on a Mac.
    - - + + \ No newline at end of file diff --git a/docs/general/wasp-ts-config.html b/docs/general/wasp-ts-config.html index b960d2ebed..e37bddcb96 100644 --- a/docs/general/wasp-ts-config.html +++ b/docs/general/wasp-ts-config.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.15.0

    Wasp TypeScript config (*.wasp.ts)

    Requires Wasp >= 0.15

    This document assumes your app works with Wasp >= 0.15.
    -If you haven't migrated your app yet, follow the migration instructions and verify everything works. After that, come back here and try out the new Wasp TS config.

    Early preview

    This feature is currently in early preview and we are actively working on it.

    In Wasp, you normally define/configure the high level of your app (pages, routes, queries, actions, auth, ...) in a main.wasp file in the root of your project. In main.wasp you write in Wasp's DSL (domain-specific language), which is a simple configuration language similar to JSON but smarter.

    Wasp 0.15 introduces the Wasp TS config, an alternative way to define the high level of your app via main.wasp.ts! Although it looks similar to how you would do it in main.wasp, the difference is that you write in TypeScript, not in Wasp's DSL.

    Wasp TS config is an early preview feature, meaning it is a little rough and not yet where it could be, but it does work. We think it's pretty cool already, and you can try it out now. If you do, please share your feedback and ideas with us on our GitHub or Discord . This is crucial for us to be able to shape this feature in the best possible way!

    Motivation​

    • Out-of-the-box support in all editors.
    • Less maintenance on our side.
    • More flexibility for you while writing the config.
    • It will enable us to easily add support for multiple Wasp files in the future.
    • A great foundation for the Full Stack Modules (FSM) that are a part of our future plans.

    How to switch from the Wasp DSL config to the Wasp TS config​

    1. Go into the Wasp project you want to switch to the Wasp TS config (or create a new Wasp project if you want to try it out like that). Make sure you are on Wasp >= 0.15 and your project is working.

    2. Rename tsconfig.json file to tsconfig.src.json and add "include": ["src"] entry to the top level (next to compilerOptions, not in them!):

      tsconfig.src.json
      {
        "compilerOptions": {
          ...
        },
        ...
        "include": ["src"]
      }

    3. Create a new tsconfig.json file with the following content:

      tsconfig.json
      {
        "files": [],
        "references": [
          { "path": "./tsconfig.src.json" },
          { "path": "./tsconfig.wasp.json" }
        ]
      }

    4. Create a new tsconfig.wasp.json file with the following content:

      tsconfig.wasp.json
      {
        "compilerOptions": {
          "skipLibCheck": true,
          "target": "ES2022",
          "isolatedModules": true,
          "moduleDetection": "force",

          // linting
          "strict": true,
          "noUnusedLocals": true,
          "noUnusedParameters": true,

          "module": "NodeNext",
          "noEmit": true,

          "lib": ["ES2023"],
        },
        "include": ["main.wasp.ts"]
      }

    5. Add "type": "module" to the top level of your package.json:

      package.json
      {
        "type": "module",
        ...
      }

    6. Rename the main.wasp file to main.wasp.old. You'll want to use it as a reference while writing main.wasp.ts.

    7. Run wasp clean and rm package-lock.json. This ensures you start from a clean state.

    8. Run wasp ts-setup. This command will add the wasp-config package to your package.json's devDependencies.

    9. Create an empty main.wasp.ts file and rewrite your main.wasp.old in it but in TypeScript.

      Check out the reference main.wasp.ts file below for details on what the TypeScript API for configuring Wasp looks like. -In short, you'll have to:

    10. Import App from wasp-config

    11. Create a new app object with new App().

    12. Use the app object to define parts of your web app like auth, pages, query, api...

    13. Export the app from your file using a default export.

      You can manually do the rewrite using the reference file and TS types as guides (IDE support should work for you in main.wasp.ts), or you can (and we recommend it!) give the reference main.wasp.ts file to the LLM of your choice and tell it to rewrite your main.wasp while following the format in the reference file: we had great results with this!

    14. Run wasp start to run your app! If you got everything right, your app should work exactly like it did before. The only difference is that it's now reading the Wasp config from main.wasp.ts instead of main.wasp.

      tip

      Don't forget to have the database running or do the db migrations if needed, as you would normally when running your app in development.

    15. That is it, you are now using Wasp TS config! You can delete main.wasp.old file now if you still have it around.

    caution

    If you run wasp clean or remove node_modules on your own, you will have to rerun wasp ts-setup!

    Got stuck on any of these steps? Let us know in our Discord and we will help!

    What next?​

    Experiment​

    Play with the Wasp TS config, get the feel of it, and see if you can find ways to improve it. Here are some ideas you can experiment with:

    • How would you reduce the boilerplate in main.wasp.ts file? Helper functions, loops?
    • Can you imagine a better API or better abstractions? If you can, what would that look like? Perhaps you can even implement it on top of our API?
    • Give a try at implementing your own file-based routing if that is what you like: you are now in Turing complete language and have access to the disk!
    • Surprise us!

    Feedback​

    Whatever you end up doing, we would love it if you would let us know how it was and show us what you did.

    We do have some immediate ideas of our own about what we want to improve, but we want to hear what you thought of, what you liked or disliked, or what you came up with. Even if you just found it all good, or just a single thing you didn't or did like, that is also valuable feedback and we would love to hear it!

    Let us know on our GitHub or, even better, in our Discord .

    Reference main.wasp.ts file​

    main.wasp.ts
    import { App } from 'wasp-config'

    const app = new App('todoApp', {
      title: 'ToDo App',
      wasp: { version: '^0.15.0' },
      // head: []
    });

    app.webSocket({
      fn: { import: 'webSocketFn', from: '@src/webSocket' },
      // autoConnect: false
    });

    app.auth({
      userEntity: 'User',
      methods: {
        discord: {
          configFn: { import: 'config', from: '@src/auth/discord' },
          userSignupFields: { import: 'userSignupFields', from: '@src/auth/discord' }
        },
        google: {
          configFn: { import: 'config', from: '@src/auth/google' },
          userSignupFields: { import: 'userSignupFields', from: '@src/auth/google' }
        },
        gitHub: {
          configFn: { import: 'config', from: '@src/auth/github.js' },
          userSignupFields: { import: 'userSignupFields', from: '@src/auth/github.js' }
        },
        // keycloak: {},
        // email: {
        //   userSignupFields: { import: 'userSignupFields', from: '@src/auth/email' },
        //   fromField: {
        //     name: 'ToDO App',
        //     email: 'mihovil@ilakovac.com'
        //   },
        //   emailVerification: {
        //     getEmailContentFn: { import: 'getVerificationEmailContent', from: '@src/auth/email' },
        //     clientRoute: 'EmailVerificationRoute',
        //   },
        //   passwordReset: {
        //     getEmailContentFn: { import: 'getPasswordResetEmailContent', from: '@src/auth/email' },
        //     clientRoute: 'PasswordResetRoute'
        //   }
        // },
      },
      onAuthFailedRedirectTo: '/login',
      onAuthSucceededRedirectTo: '/profile',
      onBeforeSignup: { import: 'onBeforeSignup', from: '@src/auth/hooks.js' },
      onAfterSignup: { import: 'onAfterSignup', from: '@src/auth/hooks.js' },
      onBeforeOAuthRedirect: { import: 'onBeforeOAuthRedirect', from: '@src/auth/hooks.js' },
      onBeforeLogin: { import: 'onBeforeLogin', from: '@src/auth/hooks.js' },
      onAfterLogin: { import: 'onAfterLogin', from: '@src/auth/hooks.js' }
    });

    app.server({
      setupFn: { importDefault: 'setup', from: '@src/serverSetup' },
      middlewareConfigFn: { import: 'serverMiddlewareFn', from: '@src/serverSetup' },
    });

    app.client({
      rootComponent: { import: 'App', from: '@src/App' },
      setupFn: { importDefault: 'setup', from: '@src/clientSetup' }
    });

    app.db({
      seeds: [
        { import: 'devSeedSimple', from: '@src/dbSeeds' },
      ]
    });

    app.emailSender({
      provider: 'SMTP',
      defaultFrom: { email: 'test@test.com' }
    });

    const loginPage = app.page('LoginPage', {
      component: { importDefault: 'Login', from: '@src/pages/auth/Login' }
    });
    app.route('LoginRoute', { path: '/login', to: loginPage });

    app.query('getTasks', {
      fn: { import: 'getTasks', from: '@src/queries' },
      entities: ['Task']
    });

    app.action('createTask', {
      fn: { import: 'createTask', from: '@src/actions' },
      entities: ['Task']
    });

    app.apiNamespace('bar', {
      middlewareConfigFn: { import: 'barNamespaceMiddlewareFn', from: '@src/apis' },
      path: '/bar'
    });

    app.api('barBaz', {
      fn: { import: 'barBaz', from: '@src/apis' },
      auth: false,
      entities: ['Task'],
      httpRoute: ['GET', '/bar/baz']
    });

    app.job('mySpecialJob', {
      executor: 'PgBoss',
      perform: {
        fn: { import: 'foo', from: '@src/jobs/bar' },
        executorOptions: {
          pgBoss: { retryLimit: 1 }
        }
      },
      entities: ['Task']
    });

    export default app;
    - - +If you haven't migrated your app yet, follow the migration instructions and verify everything works. After that, come back here and try out the new Wasp TS config.

    Early preview

    This feature is currently in early preview and we are actively working on it.

    In Wasp, you normally define/configure the high level of your app (pages, routes, queries, actions, auth, ...) in a main.wasp file in the root of your project. In main.wasp you write in Wasp's DSL (domain-specific language), which is a simple configuration language similar to JSON but smarter.

    Wasp 0.15 introduces the Wasp TS config, an alternative way to define the high level of your app via main.wasp.ts! Although it looks similar to how you would do it in main.wasp, the difference is that you write in TypeScript, not in Wasp's DSL.

    Wasp TS config is an early preview feature, meaning it is a little rough and not yet where it could be, but it does work. We think it's pretty cool already, and you can try it out now. If you do, please share your feedback and ideas with us on our GitHub or Discord . This is crucial for us to be able to shape this feature in the best possible way!

    Motivation​

    • Out-of-the-box support in all editors.
    • Less maintenance on our side.
    • More flexibility for you while writing the config.
    • It will enable us to easily add support for multiple Wasp files in the future.
    • A great foundation for the Full Stack Modules (FSM) that are a part of our future plans.

    How to switch from the Wasp DSL config to the Wasp TS config​

    1. Go into the Wasp project you want to switch to the Wasp TS config (or create a new Wasp project if you want to try it out like that). Make sure you are on Wasp >= 0.15 and your project is working.

    2. Rename tsconfig.json file to tsconfig.src.json and add "include": ["src"] entry to the top level (next to compilerOptions, not in them!):

      tsconfig.src.json
      {
        "compilerOptions": {
          ...
        },
        ...
        "include": ["src"]
      }

    3. Create a new tsconfig.json file with the following content:

      tsconfig.json
      {
        "files": [],
        "references": [
          { "path": "./tsconfig.src.json" },
          { "path": "./tsconfig.wasp.json" }
        ]
      }

    4. Create a new tsconfig.wasp.json file with the following content:

      tsconfig.wasp.json
      {
        "compilerOptions": {
          "skipLibCheck": true,
          "target": "ES2022",
          "isolatedModules": true,
          "moduleDetection": "force",

          // linting
          "strict": true,
          "noUnusedLocals": true,
          "noUnusedParameters": true,

          "module": "NodeNext",
          "noEmit": true,

          "lib": ["ES2023"],
        },
        "include": ["main.wasp.ts"]
      }

    5. Add "type": "module" to the top level of your package.json, if you don't have it yet:

      package.json
      {
        "type": "module",
        ...
      }

    6. Rename the main.wasp file to main.wasp.old. You'll want to use it as a reference while writing main.wasp.ts.

    7. Run wasp clean and rm package-lock.json. This ensures you start from a clean state.

    8. Run wasp ts-setup. This command will add the wasp-config package to your package.json's devDependencies.

    9. Create an empty main.wasp.ts file and rewrite your main.wasp.old in it but in TypeScript.

      Check out the reference main.wasp.ts file below for details on what the TypeScript API for configuring Wasp looks like. +In short, you'll have to:

      1. Import App from wasp-config
      2. Create a new app object with new App().
      3. Use the app object to define parts of your web app like auth, pages, query, api...
      4. Export the app from your file using a default export.

      You can manually do the rewrite using the reference file and TS types as guides (IDE support should work for you in main.wasp.ts), or you can (and we recommend it!) give the reference main.wasp.ts file to the LLM of your choice and tell it to rewrite your main.wasp while following the format in the reference file: we had great results with this!

    10. Run wasp start to run your app! If you got everything right, your app should work exactly like it did before. The only difference is that it's now reading the Wasp config from main.wasp.ts instead of main.wasp.

      tip

      Don't forget, during wasp start, to have the database running or do the db migrations if needed, as you would normally when running your app in development.

    11. That is it, you are now using Wasp TS config! You can delete main.wasp.old file now if you still have it around.

    caution

    If you run wasp clean or remove node_modules on your own, you will have to rerun wasp ts-setup!

    Got stuck on any of these steps? Let us know in our Discord and we will help!

    What next?​

    Experiment​

    Play with the Wasp TS config, get the feel of it, and see if you can find ways to improve it. Here are some ideas you can experiment with:

    • How would you reduce the boilerplate in main.wasp.ts file? Helper functions, loops?
    • Can you imagine a better API or better abstractions? If you can, what would that look like? Perhaps you can even implement it on top of our API?
    • Give a try at implementing your own file-based routing if that is what you like: you are now in Turing complete language and have access to the disk!
    • Surprise us!

    Feedback​

    Whatever you end up doing, we would love it if you would let us know how it was and show us what you did.

    We do have some immediate ideas of our own about what we want to improve, but we want to hear what you thought of, what you liked or disliked, or what you came up with. Even if you just found it all good, or just a single thing you didn't or did like, that is also valuable feedback and we would love to hear it!

    Let us know on our GitHub or, even better, in our Discord .

    Reference main.wasp.ts file​

    main.wasp.ts
    import { App } from 'wasp-config'

    const app = new App('todoApp', {
      title: 'ToDo App',
      wasp: { version: '^0.15.0' },
      // head: []
    });

    app.webSocket({
      fn: { import: 'webSocketFn', from: '@src/webSocket' },
      // autoConnect: false
    });

    app.auth({
      userEntity: 'User',
      methods: {
        discord: {
          configFn: { import: 'config', from: '@src/auth/discord' },
          userSignupFields: { import: 'userSignupFields', from: '@src/auth/discord' }
        },
        google: {
          configFn: { import: 'config', from: '@src/auth/google' },
          userSignupFields: { import: 'userSignupFields', from: '@src/auth/google' }
        },
        gitHub: {
          configFn: { import: 'config', from: '@src/auth/github.js' },
          userSignupFields: { import: 'userSignupFields', from: '@src/auth/github.js' }
        },
        // keycloak: {},
        // email: {
        //   userSignupFields: { import: 'userSignupFields', from: '@src/auth/email' },
        //   fromField: {
        //     name: 'ToDO App',
        //     email: 'mihovil@ilakovac.com'
        //   },
        //   emailVerification: {
        //     getEmailContentFn: { import: 'getVerificationEmailContent', from: '@src/auth/email' },
        //     clientRoute: 'EmailVerificationRoute',
        //   },
        //   passwordReset: {
        //     getEmailContentFn: { import: 'getPasswordResetEmailContent', from: '@src/auth/email' },
        //     clientRoute: 'PasswordResetRoute'
        //   }
        // },
      },
      onAuthFailedRedirectTo: '/login',
      onAuthSucceededRedirectTo: '/profile',
      onBeforeSignup: { import: 'onBeforeSignup', from: '@src/auth/hooks.js' },
      onAfterSignup: { import: 'onAfterSignup', from: '@src/auth/hooks.js' },
      onBeforeOAuthRedirect: { import: 'onBeforeOAuthRedirect', from: '@src/auth/hooks.js' },
      onBeforeLogin: { import: 'onBeforeLogin', from: '@src/auth/hooks.js' },
      onAfterLogin: { import: 'onAfterLogin', from: '@src/auth/hooks.js' }
    });

    app.server({
      setupFn: { importDefault: 'setup', from: '@src/serverSetup' },
      middlewareConfigFn: { import: 'serverMiddlewareFn', from: '@src/serverSetup' },
    });

    app.client({
      rootComponent: { import: 'App', from: '@src/App' },
      setupFn: { importDefault: 'setup', from: '@src/clientSetup' }
    });

    app.db({
      seeds: [
        { import: 'devSeedSimple', from: '@src/dbSeeds' },
      ]
    });

    app.emailSender({
      provider: 'SMTP',
      defaultFrom: { email: 'test@test.com' }
    });

    const loginPage = app.page('LoginPage', {
      component: { importDefault: 'Login', from: '@src/pages/auth/Login' }
    });
    app.route('LoginRoute', { path: '/login', to: loginPage });

    app.query('getTasks', {
      fn: { import: 'getTasks', from: '@src/queries' },
      entities: ['Task']
    });

    app.action('createTask', {
      fn: { import: 'createTask', from: '@src/actions' },
      entities: ['Task']
    });

    app.apiNamespace('bar', {
      middlewareConfigFn: { import: 'barNamespaceMiddlewareFn', from: '@src/apis' },
      path: '/bar'
    });

    app.api('barBaz', {
      fn: { import: 'barBaz', from: '@src/apis' },
      auth: false,
      entities: ['Task'],
      httpRoute: ['GET', '/bar/baz']
    });

    app.job('mySpecialJob', {
      executor: 'PgBoss',
      perform: {
        fn: { import: 'foo', from: '@src/jobs/bar' },
        executorOptions: {
          pgBoss: { retryLimit: 1 }
        }
      },
      entities: ['Task']
    });

    export default app;
    + + \ No newline at end of file diff --git a/docs/migration-guides/migrate-from-0-11-to-0-12.html b/docs/migration-guides/migrate-from-0-11-to-0-12.html index 5e67ab42fa..cf5e45affc 100644 --- a/docs/migration-guides/migrate-from-0-11-to-0-12.html +++ b/docs/migration-guides/migrate-from-0-11-to-0-12.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -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/migration-guides/migrate-from-0-12-to-0-13.html b/docs/migration-guides/migrate-from-0-12-to-0-13.html index 61eea67268..5e72568612 100644 --- a/docs/migration-guides/migrate-from-0-12-to-0-13.html +++ b/docs/migration-guides/migrate-from-0-12-to-0-13.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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.

    Make sure to read the migration guide from 0.13.X to 0.14.X after you finish this one.

    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/migration-guides/migrate-from-0-13-to-0-14.html b/docs/migration-guides/migrate-from-0-13-to-0-14.html index 4ea9721251..8c6c122767 100644 --- a/docs/migration-guides/migrate-from-0-13-to-0-14.html +++ b/docs/migration-guides/migrate-from-0-13-to-0-14.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -30,7 +30,7 @@ below.

    If you have made changes to your tsconfig.json file, we recommend taking the new version of the file and reapplying them.

    Here's the new version of the tsconfig.json file:

    tsconfig.json
    // =============================== IMPORTANT =================================
    //
    // This file is only used for Wasp IDE support. You can change it to configure
    // your IDE checks, but none of these options will affect the TypeScript
    // compiler. Proper TS compiler configuration in Wasp is coming soon :)
    {
      "compilerOptions": {
        "module": "esnext",
        "target": "esnext",
        // We're bundling all code in the end so this is the most appropriate option,
        // it's also important for autocomplete to work properly.
        "moduleResolution": "bundler",
        // JSX support
        "jsx": "preserve",
        "strict": true,
        // Allow default imports.
        "esModuleInterop": true,
        "lib": ["dom", "dom.iterable", "esnext"],
        "allowJs": true,
        "typeRoots": [
          // This is needed to properly support Vitest testing with jest-dom matchers.
          // Types for jest-dom are not recognized automatically and Typescript complains
          // about missing types e.g. when using `toBeInTheDocument` and other matchers.
          "node_modules/@testing-library",
          // Specifying type roots overrides the default behavior of looking at the
          // node_modules/@types folder so we had to list it explicitly.
          // Source 1: https://www.typescriptlang.org/tsconfig#typeRoots
          // Source 2: https://github.com/testing-library/jest-dom/issues/546#issuecomment-1889884843
          "node_modules/@types"
        ],
        // Since this TS config is used only for IDE support and not for
        // compilation, the following directory doesn't exist. We need to specify
        // it to prevent this error:
        // https://stackoverflow.com/questions/42609768/typescript-error-cannot-write-file-because-it-would-overwrite-input-file
        "outDir": ".wasp/phantom"
      }
    }

    Migrate to the new schema.prisma file​

    To use the new schema.prisma file, you need to move your entities from the .wasp file to the schema.prisma file.

    1. Create a new schema.prisma file

    Create a new file named schema.prisma in the root of your project:

    .
    ├── main.wasp
    ...
    ├── schema.prisma
    ├── src
    ├── tsconfig.json
    └── vite.config.ts

    2. Add the datasource block to the schema.prisma file

    This block specifies the database type and connection URL:

    schema.prisma
    datasource db {
      provider = "sqlite"
      url      = env("DATABASE_URL")
    }

    • The provider should be either "postgresql" or "sqlite".

    • The url must be set to env("DATABASE_URL") so that Wasp can inject the database URL from the environment variables.

    3. Add the generator block to the schema.prisma file

    This block specifies the Prisma Client generator Wasp uses:

    schema.prisma
    datasource db {
      provider = "sqlite"
      url      = env("DATABASE_URL")
    }

    generator client {
      provider = "prisma-client-js"
    }
    • The provider should be set to "prisma-client-js".

    4. Move your entities to the schema.prisma file

    Move the entities from the .wasp file to the schema.prisma file:

    schema.prisma
    datasource db {
      provider = "sqlite"
      url      = env("DATABASE_URL")
    }

    generator client {
      provider = "prisma-client-js"
    }

    // There are some example entities, you should move your entities here
    model User {
      id       Int @id @default(autoincrement())
      tasks    Task[]
    }

    model Task {
      id          Int @id @default(autoincrement())
      description String
      isDone      Boolean
      userId      Int
      user        User @relation(fields: [userId], references: [id])
    }

    When moving the entities over, you'll need to change entity to model and remove the =psl and psl= tags.

    If you had the following in the .wasp file:

    main.wasp
    entity Task {=psl
      // Stays the same
    psl=}

    ... it would look like this in the schema.prisma file:

    schema.prisma
    model Task {
      // Stays the same
    }

    5. Remove app.db.system field from the Wasp file

    We now configure the DB system in the schema.prisma file, so there is no need for that field in the Wasp file.

    main.wasp
    app MyApp {
      // ...
      db: {
        system: PostgreSQL,
      }
    }

    6. Migrate Prisma preview features config to the schema.prisma file

    If you didn't use any Prisma preview features, you can skip this step.

    If you had the following in the .wasp file:

    main.wasp
    app MyApp {
      // ...
      db: {
        prisma: {
          clientPreviewFeatures: ["postgresqlExtensions"]
          dbExtensions: [
            { name: "hstore", schema: "myHstoreSchema" },
            { name: "pg_trgm" },
            { name: "postgis", version: "2.1" },
          ]
        }
      }
    }

    ... it will become this:

    schema.prisma
    datasource db {
      provider = "postgresql"
      url      = env("DATABASE_URL")
      extensions = [hstore(schema: "myHstoreSchema"), pg_trgm, postgis(version: "2.1")]
    }

    generator client {
      provider = "prisma-client-js"
      previewFeatures = ["postgresqlExtensions"]
    }

    All that's left to do is migrate the database.

    To avoid type errors, it's best to take care of database migrations after you've migrated the rest of the code. So, just keep reading, and we will remind you to migrate the database as the last step of the migration guide.

    Read more about the Prisma Schema File and how Wasp uses it to generate the database schema and Prisma client.

    Migrate how you access user auth fields​

    We had to make a couple of breaking changes to reach the new simpler API.

    Follow the steps below to migrate:

    1. Replace the getUsername helper with user.identities.username.id

      If you didn't use the getUsername helper in your code, you can skip this step.

      This helper changed and it no longer works with the user you receive as a prop on a page or through the context. You'll need to replace it with user.identities.username.id.

      src/MainPage.tsx
      import { getUsername, AuthUser } from 'wasp/auth'

      const MainPage = ({ user }: { user: AuthUser }) => {
        const username = getUsername(user)
        // ...
      }
      src/tasks.ts
      import { getUsername } from 'wasp/auth'

      export const createTask: CreateTask<...>  = async (args, context) => {
          const username = getUsername(context.user)
          // ...
      }

    2. Replace the getEmail helper with user.identities.email.id

      If you didn't use the getEmail helper in your code, you can skip this step.

      This helper changed and it no longer works with the user you receive as a prop on a page or through the context. You'll need to replace it with user.identities.email.id.

      src/MainPage.tsx
      import { getEmail, AuthUser } from 'wasp/auth'

      const MainPage = ({ user }: { user: AuthUser }) => {
        const email = getEmail(user)
        // ...
      }
      src/tasks.ts
      import { getEmail } from 'wasp/auth'

      export const createTask: CreateTask<...>  = async (args, context) => {
          const email = getEmail(context.user)
          // ...
      }

    3. Replace accessing providerData with user.identities.<provider>.<value>

      If you didn't use any data from the providerData object, you can skip this step.

      Replace <provider> with the provider name (for example username, email, google, github, etc.) and <value> with the field you want to access (for example isEmailVerified).

      src/MainPage.tsx
      import { findUserIdentity, AuthUser } from 'wasp/auth'

      function getProviderData(user: AuthUser) {
        const emailIdentity = findUserIdentity(user, 'email')
        // We needed this before check for proper type support
        return emailIdentity && 'isEmailVerified' in emailIdentity.providerData
          ? emailIdentity.providerData
          : null
      }

      const MainPage = ({ user }: { user: AuthUser }) => {
        const providerData = getProviderData(user)
        const isEmailVerified = providerData ? providerData.isEmailVerified : null
        // ...
      }

    4. Use getFirstProviderUserId directly on the user object

      If you didn't use getFirstProviderUserId in your code, you can skip this step.

      You should replace getFirstProviderUserId(user) with user.getFirstProviderUserId().

      src/MainPage.tsx
      import { getFirstProviderUserId, AuthUser } from 'wasp/auth'

      const MainPage = ({ user }: { user: AuthUser }) => {
        const userId = getFirstProviderUserId(user)
        // ...
      }
      src/tasks.ts
      import { getFirstProviderUserId } from 'wasp/auth'

      export const createTask: CreateTask<...>  = async (args, context) => {
          const userId = getFirstProviderUserId(context.user)
          // ...
      }

    5. Replace findUserIdentity with checks on user.identities.<provider>

      If you didn't use findUserIdentity in your code, you can skip this step.

      Instead of using findUserIdentity to get the identity object, you can directly check if the identity exists on the identities object.

      src/MainPage.tsx
      import { findUserIdentity, AuthUser } from 'wasp/auth'

      const MainPage = ({ user }: { user: AuthUser }) => {
        const usernameIdentity = findUserIdentity(user, 'username')
        if (usernameIdentity) {
          // ...
        }
      }
      src/tasks.ts
      import { findUserIdentity } from 'wasp/auth'

      export const createTask: CreateTask<...>  = async (args, context) => {
          const usernameIdentity = findUserIdentity(context.user, 'username')
          if (usernameIdentity) {
              // ...
          }
      }

    Migrate the database​

    Finally, you can Run the Wasp CLI to regenerate the new Prisma client:

    wasp db migrate-dev

    This command generates the Prisma client based on the schema.prisma file.

    Read more about the Prisma Schema File and how Wasp uses it to generate the database schema and Prisma client.

    That's it!

    You should now be able to run your app with the new Wasp 0.14.0. We recommend reading through the updated Accessing User Data section to get a better understanding of the new API.

    - - + + \ No newline at end of file diff --git a/docs/migration-guides/migrate-from-0-14-to-0-15.html b/docs/migration-guides/migrate-from-0-14-to-0-15.html index 26c07b8dbd..9cdc54fd02 100644 --- a/docs/migration-guides/migrate-from-0-14-to-0-15.html +++ b/docs/migration-guides/migrate-from-0-14-to-0-15.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    Migration from 0.14.X to 0.15.X

    What's new in 0.15.0?​

    Wasp 0.15.0 brings upgrades to some of Wasp's most important dependencies. Let's see what's new.

    Prisma 5​

    Wasp is now using the latest Prisma 5, which brings a lot of performance improvements and new features.

    From the Prisma docs:

    Prisma ORM 5.0.0 introduces a number of changes, including the usage of our new JSON Protocol, which make Prisma Client faster by default.

    This means that your Wasp app will be faster and more reliable with the new Prisma 5 version.

    React Router 6​

    Wasp also upgraded its React Router version from 5.3.4 to 6.26.2. This means that we are now using the latest React Router version, which brings us up to speed and opens up new possibilities for Wasp e.g. potentially using loaders and actions in the future.

    There are some breaking changes in React Router 6, so you will need to update your app to use the new hooks and components.

    How to migrate?​

    To migrate your Wasp app from 0.14.X to 0.15.X, follow these steps:

    1. Bump the Wasp version​

    Update the version field in your Wasp file to ^0.15.0:

    main.wasp
    app MyApp {
      wasp: {
        version: "^0.15.0"
      },
    }

    2. Update the package.json file​

    1. Update the prisma version in your package.json file to 5.19.1, and add "type": "module" to the top level:

      package.json
      {
        ...
        "type": "module",
        "dependencies": {
          ....
          "prisma": "5.19.1"
        }
        ...
      }

    2. If you have @types/react-router-dom in your package.json, you can remove it as it is no longer needed.

    3. Use the latest React Router APIs​

    Update the usage of the old React Router 5 APIs to the new React Router 6 APIs:

    1. If you used the useHistory() hook, you should now use the useNavigate() hook.

      src/SomePage.tsx
      import { useHistory } from 'react-router-dom'

      export function SomePage() {
        const history = useHistory()
        const handleClick = () => {
          history.push('/new-route')
        }
        return <button onClick={handleClick}>Go to new route</button>
      }

      Check the React Router 6 docs for more information on the useNavigate() hook.

    2. If you used the <Redirect /> component, you should now use the <Navigate /> component.

      The default behaviour changed from replace to push in v6, so if you want to keep the old behaviour, you should add the replace prop.

      src/SomePage.tsx
      import { Redirect } from 'react-router-dom'

      export function SomePage() {
        return (
          <Redirect to="/new-route" />
        )
      }

      Check the React Router 6 docs for more information on the <Navigate /> component.

    3. If you accessed the route params using props.match.params, you should now use the useParams() hook.

      src/SomePage.tsx
      import { RouteComponentProps } from 'react-router-dom'

      export function SomePage(props: RouteComponentProps) {
        const { id } = props.match.params
        return (
          <div>
            <h1>Item {id}</h1>
          </div>
        )
      }

      Check the React Router 6 docs for more information on the useParams() hook.

    4. If you used the <NavLink /> component and its isActive prop to set the active link state, you should now set the className prop directly.

      src/SomePage.tsx
      import { NavLink } from 'react-router-dom'

      export function SomePage() {
        return (
          <NavLink
            to="/new-route"
            isActive={(_match, location) => {
              return location.pathname === '/new-route'
            }}
            className={(isActive) =>
              cn('text-blue-500', {
                underline: isActive,
              })
            }
          >
            Go to new route
          </NavLink>
        )
      }

      Check the React Router 6 docs for more information on the <NavLink /> component.

    4. Update your root component​

    The client.rootComponent now requires rendering <Outlet /> instead the children prop.

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      client: {
        rootComponent: import { App } from "@src/App.tsx",
      }
    }
    src/App.tsx
    export function App({ children }: { children: React.ReactNode }) {
      return (
        <div>
          <header>
            <h1>My App</h1>
          </header>
          {children}
          <footer>
            <p>My App footer</p>
          </footer>
        </div>
      )
    }

    That's it!

    You should now be able to run your app with the new Wasp 0.15.0.

    - - + + \ No newline at end of file diff --git a/docs/project/client-config.html b/docs/project/client-config.html index 75ce84fdd8..e4849461a4 100644 --- a/docs/project/client-config.html +++ b/docs/project/client-config.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -36,7 +36,7 @@ renders a custom layout:

    src/Root.jsx
    import { Outlet } from 'react-router-dom'
    import store from './store'
    import { Provider } from 'react-redux'

    export default function Root() {
      return (
        <Provider store={store}>
          <Layout />
        </Provider>
      )
    }

    function Layout() {
      return (
        <div>
          <header>
            <h1>My App</h1>
          </header>
          <Outlet />
          <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 d1875e2772..2a7b6522d7 100644 --- a/docs/project/css-frameworks.html +++ b/docs/project/css-frameworks.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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 ee2e7619cf..34574376dd 100644 --- a/docs/project/custom-vite-config.html +++ b/docs/project/custom-vite-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.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 34f51ce83b..ebb76c9b85 100644 --- a/docs/project/customizing-app.html +++ b/docs/project/customizing-app.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.15.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.15.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.15.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.15.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.15.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:

    • wasp: dict required Wasp compiler configuration. It is a dictionary with a single field:

      • version: string required

        The version specifies which versions of Wasp are compatible with the app. It should contain a valid SemVer range

        info

        For now, the version field only supports caret ranges (i.e., ^x.y.z). Support for the full specification will come in a future version of Wasp

    • title: string required

      Title of your app. It will appear in the browser tab, next to the favicon.

    • head: [string]

      List of additional lines (e.g. <link> or <script> tags) to be included in the <head> of your HTML document.

    The rest of the fields are covered in dedicated sections of the docs:

    - - + + \ No newline at end of file diff --git a/docs/project/dependencies.html b/docs/project/dependencies.html index ce62eee215..af4b37820c 100644 --- a/docs/project/dependencies.html +++ b/docs/project/dependencies.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.15.0

    Dependencies

    In a Wasp project, dependencies are defined in a standard way for JavaScript projects: using the package.json file, located at the root of your project. You can list your dependencies under the dependencies or devDependencies fields.

    Adding a New Dependency​

    To add a new package, like date-fns (a great date handling library), you use npm:

    npm install date-fns

    This command will add the package in the dependencies section of your package.json file.

    You will notice that there are some other packages in the dependencies section, like react and wasp. These are the packages that Wasp uses internally, and you should not modify or remove them.

    Using Packages that are Already Used by Wasp Internally​

    In the current version of Wasp, if Wasp is already internally using a certain dependency (e.g. React) with a certain version specified, you are not allowed to define that same npm dependency yourself while specifying a different version.

    If you do that, you will get an error message telling you which exact version you have to use for that dependency. This means Wasp dictates exact versions of certain packages, so for example you can't choose the version of React you want to use.

    note

    We are currently working on a restructuring that will solve this and some other quirks: check issue #734 to follow our progress.

    - - + + \ No newline at end of file diff --git a/docs/project/env-vars.html b/docs/project/env-vars.html index 01c6000c9c..0e38eebc6a 100644 --- a/docs/project/env-vars.html +++ b/docs/project/env-vars.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -28,7 +28,7 @@ By default, in the .gitignore file that comes with a new Wasp app, we ignore all dotenv files.

    Dotenv files

    dotenv files are a popular method for storing configuration: to learn more about them in general, check out the dotenv npm package.

    2. Using Shell​

    If you set environment variables in the shell where you run your Wasp commands (e.g., wasp start), Wasp will recognize them.

    You can set environment variables in the .profile or a similar file, which will set them permanently, or you can set them temporarily by defining them at the start of a command (SOME_VAR_NAME=SOMEVALUE wasp start).

    This is not specific to Wasp and is simply how environment variables can be set in the shell.

    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 during development, you should use .env files instead. However, it can be useful for occasionally overriding specific environment variables because environment variables set this way take precedence over those defined in .env files.

    Defining Env Vars in Production​

    While in development, we had the option of using .env.client and .env.server files which made it easy to define and manage env vars. However, for production, .env.client and .env.server files will be ignored, and we need to provide env vars differently.

    Env vars usage in development and production

    Client Env Vars​

    Client env vars are embedded into the client code during the build process, making them public and readable by anyone. Therefore, you should never store secrets in them (such as secret API keys).

    When building for production .env.client will be ignored, since it is meant to be used only during development. Instead, you should provide the production client env vars directly to the build command that turns client code into static files:

    REACT_APP_SOME_VAR_NAME=somevalue REACT_APP_SOME_OTHER_VAR_NAME=someothervalue npm run build

    Check the deployment docs for more details.

    Also, notice that you can't and shouldn't provide env vars to the client code by setting them on the hosting provider where you deployed them (unlike server env vars, where this is how you should do it). Your client code will ignore those, as at that point client code is just static files.

    How it works

    What happens behind the scenes is that Wasp will replace all occurrences of import.meta.env.REACT_APP_SOME_VAR_NAME in your client code with the env var value you provided. This is done during the build process, so the value is embedded into the static files produced from the client code.

    Read more about it in Vite's docs.

    Server Env Vars​

    When building for production .env.server will be ignored, since it is meant to be used only during development.

    You can provide production env vars to your server code in production by defining them and making them available on the server where your server code is running.

    Setting this up will highly depend on where you are deploying your Wasp project, but in general it comes down to defining the env vars via mechanisms that your hosting provider provides.

    For example, if you deploy your project to Fly, you can define them using the flyctl CLI tool:

    flyctl secrets set SOME_VAR_NAME=somevalue

    You can read a lot more details in the deployment section of the docs. We go into detail on how to define env vars for each deployment option.

    - - + + \ No newline at end of file diff --git a/docs/project/server-config.html b/docs/project/server-config.html index f755b8135c..1a22c1da22 100644 --- a/docs/project/server-config.html +++ b/docs/project/server-config.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    Server Config

    You can configure the behavior of the server via the server field of app declaration:

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      server: {
        setupFn: import { mySetupFunction } from "@src/myServerSetupCode.js",
        middlewareConfigFn: import { myMiddlewareConfigFn } from "@src/myServerSetupCode.js"
      }
    }

    Setup Function​

    Adding a Custom Route​

    As an example, adding a custom route would look something like:

    src/myServerSetupCode.ts
    export const mySetupFunction = async ({ app }) => {
      addCustomRoute(app)
    }

    function addCustomRoute(app) {
      app.get('/customRoute', (_req, res) => {
        res.send('I am a custom route')
      })
    }

    Storing Some Values for Later Use​

    In case you want to store some values for later use, or to be accessed by the Operations you do that in the setupFn function.

    Dummy example of such function and its usage:

    src/myServerSetupCode.js
    let someResource = undefined

    export const mySetupFunction = async () => {
      // Let's pretend functions setUpSomeResource and startSomeCronJob
      // are implemented below or imported from another file.
      someResource = await setUpSomeResource()
      startSomeCronJob()
    }

    export const getSomeResource = () => someResource
    src/queries.js
    import { getSomeResource } from './myServerSetupCode.js'

    ...

    export const someQuery = async (args, context) => {
      const someResource = getSomeResource()
      return queryDataFromSomeResource(args, someResource)
    }
    note

    The recommended way is to put the variable in the same module where you defined the setup function and then expose additional functions for reading those values, which you can then import directly from Operations and use.

    This effectively turns your module into a singleton whose construction is performed on server start.

    Read more about server setup function below.

    Middleware Config Function​

    You can configure the global middleware via the middlewareConfigFn. This will modify the middleware stack for all operations and APIs.

    Read more about middleware config function below.

    API Reference​

    main.wasp
    app MyApp {
      title: "My app",
      // ...
      server: {
        setupFn: import { mySetupFunction } from "@src/myServerSetupCode.js",
        middlewareConfigFn: import { myMiddlewareConfigFn } from "@src/myServerSetupCode.js"
      }
    }

    app.server is a dictionary with the following fields:

    • setupFn: ExtImport​

      setupFn declares a function that will be executed on server start. This function is expected to be async and will be awaited before the server starts accepting any requests.

      It allows you to do any custom setup, e.g. setting up additional database/websockets or starting cron/scheduled jobs.

      The setupFn function receives the express.Application and the http.Server instances as part of its context. They can be useful for setting up any custom server logic.

      src/myServerSetupCode.js
      export const mySetupFunction = async () => {
        await setUpSomeResource()
      }

    • middlewareConfigFn: ExtImport​

      The import statement to an Express middleware config function. This is a global modification affecting all operations and APIs. See more in the configuring middleware section.

    - - + + \ No newline at end of file diff --git a/docs/project/starter-templates.html b/docs/project/starter-templates.html index 905c642c70..cf4fc3defa 100644 --- a/docs/project/starter-templates.html +++ b/docs/project/starter-templates.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.15.0

    Starter Templates

    We created a few starter templates to help you get started with Wasp. Check out the list below.

    Using a Template​

    Run wasp new to run the interactive mode for creating a new Wasp project.

    It will ask you for the project name, and then for the template to use:

    $ 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

    Available Templates​

    When you have a good idea for a new product, you don't want to waste your time on setting up common things like authentication, database, etc. That's why we created a few starter templates to help you get started with Wasp.

    OpenSaaS.sh template​

    SaaS Template

    Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check out https://opensaas.sh/ for more details.

    Features: Stripe Payments, OpenAI GPT API, Google Auth, SendGrid, Tailwind, & Cron Jobs

    Use this template:

    wasp new <project-name> -t saas

    Vector Similarity Search Template​

    Vector Similarity Search Template

    A template for generating embeddings and performing vector similarity search on your text data!

    Features: Embeddings & vector similarity search, OpenAI Embeddings API, Vector DB (Pinecone), Tailwind, Full-stack Type Safety

    Use this template:

    wasp new <project-name> -t embeddings

    Todo App w/ Typescript​

    A simple Todo App with Typescript and Full-stack Type Safety.

    Features: Auth (username/password), Full-stack Type Safety

    Use this template:

    wasp new <project-name> -t todo-ts

    AI Generated Starter 🤖​

    Using the same tech as used on https://usemage.ai/, Wasp generates your custom starter template based on your project description. It will automatically generate your data model, auth, queries, actions and React pages.

    You will need to provide your own OpenAI API key to be able to use this template.

    Features: Generated using OpenAI's GPT models, Auth (username/password), Queries, Actions, Pages, Full-stack Type Safety

    - - + + \ No newline at end of file diff --git a/docs/project/static-assets.html b/docs/project/static-assets.html index c8affb9946..2268a6d33c 100644 --- a/docs/project/static-assets.html +++ b/docs/project/static-assets.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    Static Asset Handling

    Importing an Asset as URL​

    Importing a static asset (e.g. an image) will return its URL. For example:

    src/App.jsx
    import imgUrl from './img.png'

    function App() {
      return <img src={imgUrl} alt="img" />
    }

    For example, imgUrl will be /img.png during development, and become /assets/img.2d8efhg.png in the production build.

    This is what you want to use most of the time, as it ensures that the asset file exists and is included in the bundle.

    We are using Vite under the hood, read more about importing static assets in Vite's docs.

    The public Directory​

    If you have assets that are:

    • Never referenced in source code (e.g. robots.txt)
    • Must retain the exact same file name (without hashing)
    • ...or you simply don't want to have to import an asset first just to get its URL

    Then you can place the asset in the public directory at the root of your project:

    .
    └── public
        ├── favicon.ico
        └── robots.txt

    Assets in this directory will be served at root path / during development and copied to the root of the dist directory as-is.

    For example, if you have a file favicon.ico in the public directory, and your app is hosted at https://myapp.com, it will be made available at https://myapp.com/favicon.ico.

    Usage in client code

    Note that:

    • You should always reference public assets using root absolute path
      • for example, public/icon.png should be referenced in source code as /icon.png.
    • Assets in the public directory cannot be imported from .
    - - + + \ No newline at end of file diff --git a/docs/project/testing.html b/docs/project/testing.html index 75e199c046..1767113c01 100644 --- a/docs/project/testing.html +++ b/docs/project/testing.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    Testing

    info

    Wasp is in beta, so keep in mind there might be some kinks / bugs, and possibly some changes with testing support in the future. If you encounter any issues, reach out to us on Discord and we will make sure to help you out!

    Testing Your React App​

    Wasp enables you to quickly and easily write both unit tests and React component tests for your frontend code. Because Wasp uses Vite, we support testing web apps through Vitest.

    Included Libraries

    vitest: Unit test framework with native Vite support.

    @vitest/ui: A nice UI for seeing your test results.

    jsdom: A web browser test environment for Node.js.

    @testing-library/react / @testing-library/jest-dom: Testing helpers.

    msw: A server mocking library.

    Writing Tests​

    For Wasp to pick up your tests, they should be placed within the src directory and use an extension that matches these glob patterns. Some of the file names that Wasp will pick up as tests:

    • yourFile.test.ts
    • YourComponent.spec.jsx

    Within test files, you can import your other source files as usual. For example, if you have a component Counter.jsx, you test it by creating a file in the same directory called Counter.test.jsx and import the component with import Counter from './Counter'.

    Running Tests​

    Running wasp test client will start Vitest in watch mode and recompile your Wasp project when changes are made.

    • If you want to see a real-time UI, pass --ui as an option.
    • To run the tests just once, use wasp test client run.

    All arguments after wasp test client are passed directly to the Vitest CLI, so check out their documentation for all of the options.

    Be Careful

    You should not run wasp test while wasp start is running. Both will try to compile your project to .wasp/out.

    React Testing Helpers​

    Wasp provides several functions to help you write React tests:

    • renderInContext: Takes a React component, wraps it inside a QueryClientProvider and Router, and renders it. This is the function you should use to render components in your React component tests.

      import { renderInContext } from "wasp/client/test";

      renderInContext(<MainPage />);

    • mockServer: Sets up the mock server and returns an object containing the mockQuery and mockApi utilities. This should be called outside of any test case, in each file that wants to use those helpers.

      import { mockServer } from "wasp/client/test";

      const { mockQuery, mockApi } = mockServer();

      • mockQuery: Takes a Wasp query to mock and the JSON data it should return.

        import { getTasks } from "wasp/client/operations";

        mockQuery(getTasks, []);
        • Helpful when your component uses useQuery.
        • Behind the scenes, Wasp uses msw to create a server request handle that responds with the specified data.
        • Mock are cleared between each test.

      • mockApi: Similar to mockQuery, but for APIs. Instead of a Wasp query, it takes a route containing an HTTP method and a path.

        import { HttpMethod } from "wasp/client";

        mockApi({ method: HttpMethod.Get, path: "/foor/bar" }, { res: "hello" });

    Testing Your Server-Side Code​

    Wasp currently does not provide a way to test your server-side code, but we will be adding support soon. You can track the progress at this GitHub issue and express your interest by commenting.

    Examples​

    You can see some tests in a Wasp project here.

    Client Unit Tests​

    src/helpers.js
    export function areThereAnyTasks(tasks) {
      return tasks.length === 0;
    }
    src/helpers.test.js
    import { test, expect } from "vitest";

    import { areThereAnyTasks } from "./helpers";

    test("areThereAnyTasks", () => {
      expect(areThereAnyTasks([])).toBe(false);
    });

    React Component Tests​

    src/Todo.jsx
    import { useQuery, getTasks } from "wasp/client/operations";

    const Todo = (_props) => {
      const { data: tasks } = useQuery(getTasks);
      return (
        <ul>
          {tasks &&
            tasks.map((task) => (
              <li key={task.id}>
                <input type="checkbox" value={task.isDone} />
                {task.description}
              </li>
            ))}
        </ul>
      );
    };
    src/Todo.test.jsx
    import { test, expect } from "vitest";
    import { screen } from "@testing-library/react";

    import { mockServer, renderInContext } from "wasp/client/test";
    import { getTasks } from "wasp/client/operations";
    import Todo from "./Todo";

    const { mockQuery } = mockServer();

    const mockTasks = [
      {
        id: 1,
        description: "test todo 1",
        isDone: true,
        userId: 1,
      },
    ];

    test("handles mock data", async () => {
      mockQuery(getTasks, mockTasks);

      renderInContext(<Todo />);

      await screen.findByText("test todo 1");

      expect(screen.getByRole("checkbox")).toBeChecked();

      screen.debug();
    });

    Testing With Mocked APIs​

    src/Todo.jsx
    import { api } from "wasp/client/api";

    const Todo = (_props) => {
      const [tasks, setTasks] = useState([]);
      useEffect(() => {
        api
          .get("/tasks")
          .then((res) => res.json())
          .then((tasks) => setTasks(tasks))
          .catch((err) => window.alert(err));
      });

      return (
        <ul>
          {tasks &&
            tasks.map((task) => (
              <li key={task.id}>
                <input type="checkbox" value={task.isDone} />
                {task.description}
              </li>
            ))}
        </ul>
      );
    };
    src/Todo.test.jsx
    import { test, expect } from "vitest";
    import { screen } from "@testing-library/react";

    import { mockServer, renderInContext } from "wasp/client/test";
    import Todo from "./Todo";

    const { mockApi } = mockServer();

    const mockTasks = [
      {
        id: 1,
        description: "test todo 1",
        isDone: true,
        userId: 1,
      },
    ];

    test("handles mock data", async () => {
      mockApi("/tasks", { res: mockTasks });

      renderInContext(<Todo />);

      await screen.findByText("test todo 1");

      expect(screen.getByRole("checkbox")).toBeChecked();

      screen.debug();
    });
    - - + + \ No newline at end of file diff --git a/docs/quick-start.html b/docs/quick-start.html index 3c46638073..5adc92531b 100644 --- a/docs/quick-start.html +++ b/docs/quick-start.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.15.0

    Quick Start

    Installation​

    Welcome, new Waspeteer 🐝!

    Let's create and run our first Wasp app in 3 short steps:

    1. To install Wasp on Linux / OSX / WSL (Windows), open your terminal and run:

      curl -sSL https://get.wasp-lang.dev/installer.sh | sh

      ℹ️ Wasp requires Node.js and will warn you if it is missing: check below for more details.

    2. Then, create a new app by running:

      wasp new

    3. Finally, run the app:

      cd <my-project-name>
      wasp start

    That's it 🎉 You have successfully created and served a new full-stack web app at http://localhost:3000 and Wasp is serving both frontend and backend for you.

    Something Unclear?

    Check More Details section below if anything went wrong with the installation, or if you have additional questions.

    Want an even faster start?

    Try out Wasp AI 🤖 to generate a new Wasp app in minutes just from a title and short description!

    Try Wasp Without Installing 🤔?

    Give Wasp a spin in the browser with GitHub Codespaces by following the intructions in our Tutorial App README

    What next?​

    • 👉 Check out the Todo App tutorial, which will take you through all the core features of Wasp! 👈
    • Setup your editor for working with Wasp.
    • Join us on Discord! Any feedback or questions you have, we are there for you.
    • Follow Wasp development by subscribing to our newsletter: https://wasp-lang.dev/#signup . We usually send 1 per month, and Matija does his best to unleash his creativity to make them engaging and fun to read :D!

    More details​

    Requirements​

    You must have Node.js (and NPM) installed on your machine and available in PATH. A version of Node.js must be >= 18.

    If you need it, we recommend using nvm for managing your Node.js installation version(s).

    A quick guide on installing/using nvm

    Install nvm via your OS package manager (apt, pacman, homebrew, ...) or via the nvm install script.

    Then, install a version of Node.js that you need:

    nvm install 20

    Finally, whenever you need to ensure a specific version of Node.js is used, run:

    nvm use 20

    to set the Node.js version for the current shell session.

    You can run

    node -v

    to check the version of Node.js currently being used in this shell session.

    Check NVM repo for more details: https://github.com/nvm-sh/nvm.

    Installation​

    Open your terminal and run:

    curl -sSL https://get.wasp-lang.dev/installer.sh | sh
    Running Wasp on Mac with Mx chip (arm64)

    Experiencing the 'Bad CPU type in executable' issue on a device with arm64 (Apple Silicon)? Given that the wasp binary is built for x86 and not for arm64 (Apple Silicon), you'll need to install Rosetta on your Mac if you are using a Mac with Mx (M1, M2, ...). Rosetta is a translation process that enables users to run applications designed for x86 on arm64 (Apple Silicon). To install Rosetta, run the following command in your terminal

    softwareupdate --install-rosetta

    Once Rosetta is installed, you should be able to run Wasp without any issues.

    - - + + \ No newline at end of file diff --git a/docs/telemetry.html b/docs/telemetry.html index ac1a5a78ad..3f4469329f 100644 --- a/docs/telemetry.html +++ b/docs/telemetry.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.15.0

    Telemetry

    Overview​

    The term telemetry refers to the collection of certain usage data to help improve the quality of a piece of software (in this case, Wasp).

    Our telemetry implementation is anonymized and very limited in its scope, focused on answering following questions:

    • How many people and how often: tried to install Wasp, use Wasp, have built a Wasp app, or have deployed one?
    • How many projects are created with Wasp?

    When and what is sent?​

    • Information is sent via HTTPS request when wasp CLI command is invoked. Information is sent no more than twice in a period of 12 hours (sending is paused for 12 hours after last invocation, separately for wasp build command and for all other commands). Exact information as it is sent:
      {
        // Randomly generated, non-identifiable UUID representing a user.
        "distinct_id": "bf3fa7a8-1c11-4f82-9542-ec1a2d28786b",
        // Non-identifiable hash representing a project.
        "project_hash": "6d7e561d62b955d1",
        // True if command was `wasp build`, false otherwise.
        "is_build": true,
        // Captures `wasp deploy ...` args, but only those from the limited, pre-defined list of keywords.
        // Those are "fly", "setup", "create-db", "deploy" and "cmd". Everything else is ommited.
        "deploy_cmd_args": "fly;deploy",
        "wasp_version": "0.1.9.1",
        "os": "linux",
        // "CI" if running on CI, and whatever is the content of "WASP_TELEMETRY_CONTEXT" env var.
        // We use this to track when execution is happening in some special context, like on Gitpod, Replit or similar.
        "context": "CI"
      }
    • Information is also sent once via HTTPS request when wasp is installed via install.sh script. Exact information as it is sent:
      {
        // Randomly generated id.
        "distinct_id": "274701613078193779564259",
        "os": "linux"
      }

    Opting out​

    You sharing the telemetry data with us means a lot to us, since it helps us understand how popular Wasp is, how it is being used, how the changes we are doing affect usage, how many new vs old users there are, and just in general how Wasp is doing. We look at these numbers every morning and they drive us to make Wasp better.

    However, if you wish to opt-out of telemetry, we understand! You can do so by setting the WASP_TELEMETRY_DISABLE environment variable to any value, e.g.:

    export WASP_TELEMETRY_DISABLE=1

    Future plans​

    We don't have this implemented yet, but the next step will be to make telemetry go in two directions -> instead of just sending usage data to us, it will also at the same time check for any messages from our side (e.g. notification about new version of Wasp, or a security notice). Link to corresponding github issue.

    - - + + \ No newline at end of file diff --git a/docs/tutorial/actions.html b/docs/tutorial/actions.html index c6dfa507e9..8fba854b9c 100644 --- a/docs/tutorial/actions.html +++ b/docs/tutorial/actions.html @@ -18,16 +18,16 @@ - - - + + +
    Version: 0.15.0

    6. Modifying Data

    In the previous section, you learned about using Queries to fetch data. Let's now learn about Actions so you can add and update tasks in the database.

    In this section, you will create:

    1. A Wasp Action that creates a new task.
    2. A React form that calls that Action when the user creates a task.

    Creating a New Action​

    Creating an Action is very similar to creating a Query.

    Declaring an Action​

    We must first declare the Action in main.wasp:

    main.wasp
    // ...

    action createTask {
      fn: import { createTask } from "@src/actions",
      entities: [Task]
    }

    Implementing an Action​

    Let's now define a function for our createTask Action:

    src/actions.js
    export const createTask = async (args, context) => {
      return context.entities.Task.create({
        data: { description: args.description },
      })
    }
    tip

    We put the function in a new file src/actions.ts, but we could have put it anywhere we wanted! There are no limitations here, as long as the declaration in the Wasp file imports it correctly and the file is located within src directory.

    Invoking the Action on the Client​

    Start by defining a form for creating new tasks.

    src/MainPage.jsx
    import { 
      createTask, 
      getTasks, 
      useQuery 
    } from 'wasp/client/operations'

    // ... MainPage, TaskView, TaskList ...

    const NewTaskForm = () => {
      const handleSubmit = async (event) => {
        event.preventDefault()
        try {
          const target = event.target
          const description = target.description.value
          target.reset()
          await createTask({ description })
        } catch (err) {
          window.alert('Error: ' + err.message)
        }
      }

      return (
        <form onSubmit={handleSubmit}>
          <input name="description" type="text" defaultValue="" />
          <input type="submit" value="Create task" />
        </form>
      )
    }

    Unlike Queries, you can call Actions directly (without wrapping them in a hook) because they don't need reactivity. The rest is just regular React code.

    All that's left now is adding this form to the page component:

    src/MainPage.jsx
    import {
      createTask,
      getTasks,
      useQuery
    } from 'wasp/client/operations'

    const MainPage = () => {
      const { data: tasks, isLoading, error } = useQuery(getTasks)

      return (
        <div>
          <NewTaskForm />

          {tasks && <TasksList tasks={tasks} />}

          {isLoading && 'Loading...'}
          {error && 'Error: ' + error}
        </div>
      )
    }

    // ... TaskView, TaskList, NewTaskForm ...

    Great work!

    You now have a form for creating new tasks.

    Try creating a "Build a Todo App in Wasp" task and see it appear in the list below. The task is created on the server and saved in the database.

    Try refreshing the page or opening it in another browser. You'll see the tasks are still there!

    Todo App - creating new task

    Automatic Query Invalidation

    When you create a new task, the list of tasks is automatically updated to display the new task, even though you haven't written any code that does that! Wasp handles these automatic updates under the hood.

    When you declared the getTasks and createTask operations, you specified that they both use the Task entity. So when createTask is called, Wasp knows that the data getTasks fetches may have changed and automatically updates it in the background. This means that out of the box, Wasp keeps all your queries in sync with any changes made through Actions.

    This behavior is convenient as a default but can cause poor performance in large apps. While there is no mechanism for overriding this behavior yet, it is something that we plan to include in Wasp in the future. This feature is tracked here.

    A Second Action​

    Our Todo app isn't finished if you can't mark a task as done.

    We'll create a new Action to update a task's status and call it from React whenever a task's checkbox is toggled.

    Since we've already created one task together, try to create this one yourself. It should be an Action named updateTask that receives the task's id and its isDone status. You can see our implementation below.

    Solution

    Declaring the Action in main.wasp:

    main.wasp
    // ...

    action updateTask {
      fn: import { updateTask } from "@src/actions",
      entities: [Task]
    }

    Implementing the Action on the server:

    src/actions.js
    // ...

    export const updateTask = async ({ id, isDone }, context) => {
      return context.entities.Task.update({
        where: { id },
        data: {
          isDone: isDone,
        },
      })
    }

    You can now call updateTask from the React component:

    src/MainPage.jsx
    // ...
    import {
      updateTask,
      createTask,
      getTasks,
      useQuery,
    } from 'wasp/client/operations'

    // ... MainPage ...

    const TaskView = ({ task }) => {
      const handleIsDoneChange = async (event) => {
        try {
          await updateTask({
            id: task.id,
            isDone: event.target.checked,
          })
        } catch (error) {
          window.alert('Error while updating task: ' + error.message)
        }
      }

      return (
        <div>
          <input
            type="checkbox"
            id={String(task.id)}
            checked={task.isDone}
            onChange={handleIsDoneChange}
          />
          {task.description}
        </div>
      )
    }
    // ... TaskList, NewTaskForm ...

    Awesome! You can now mark this task as done.

    It's time to make one final addition to your app: supporting multiple users.

    - - + + \ No newline at end of file diff --git a/docs/tutorial/auth.html b/docs/tutorial/auth.html index e61ec2b103..64c7a25ac8 100644 --- a/docs/tutorial/auth.html +++ b/docs/tutorial/auth.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    7. Adding Authentication

    Most modern apps need a way to create and authenticate users. Wasp makes this as easy as possible with its first-class auth support.

    To add users to your app, you must:

    • Create a User Entity.
    • Tell Wasp to use the Username and Password authentication.
    • Add login and signup pages.
    • Update the main page to require authentication.
    • Add a relation between User and Task entities.
    • Modify your Queries and Actions so users can only see and modify their tasks.
    • Add a logout button.

    Creating a User Entity​

    Since Wasp manages authentication, it will create the auth related entities for you in the background. Nothing to do here!

    You must only add the User Entity to keep track of who owns which tasks:

    schema.prisma
    // ...

    model User {
      id Int @id @default(autoincrement())
    }

    Adding Auth to the Project​

    Next, tell Wasp to use full-stack authentication:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.15.0"
      },
      title: "TodoApp",
      auth: {
        // Tells Wasp which entity to use for storing users.
        userEntity: User,
        methods: {
          // Enable username and password auth.
          usernameAndPassword: {}
        },
        // We'll see how this is used in a bit.
        onAuthFailedRedirectTo: "/login"
      }
    }

    // ...

    Don't forget to update the database schema by running:

    wasp db migrate-dev

    By doing this, Wasp will create:

    • Auth UI with login and signup forms.
    • A logout() action.
    • A React hook useAuth().
    • context.user for use in Queries and Actions.
    info

    Wasp also supports authentication using Google, GitHub, and email, with more on the way!

    Adding Login and Signup Pages​

    Wasp creates the login and signup forms for us, but we still need to define the pages to display those forms on. We'll start by declaring the pages in the Wasp file:

    main.wasp
    // ...

    route SignupRoute { path: "/signup", to: SignupPage }
    page SignupPage {
      component: import { SignupPage } from "@src/SignupPage"
    }

    route LoginRoute { path: "/login", to: LoginPage }
    page LoginPage {
      component: import { LoginPage } from "@src/LoginPage"
    }

    Great, Wasp now knows these pages exist!

    Here's the React code for the pages you've just imported:

    src/LoginPage.jsx
    import { Link } from 'react-router-dom'
    import { LoginForm } from 'wasp/client/auth'

    export const LoginPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <LoginForm />
          <br />
          <span>
            I don't have an account yet (<Link to="/signup">go to signup</Link>).
          </span>
        </div>
      )
    }

    The signup page is very similar to the login page:

    src/SignupPage.jsx
    import { Link } from 'react-router-dom'
    import { SignupForm } from 'wasp/client/auth'

    export const SignupPage = () => {
      return (
        <div style={{ maxWidth: '400px', margin: '0 auto' }}>
          <SignupForm />
          <br />
          <span>
            I already have an account (<Link to="/login">go to login</Link>).
          </span>
        </div>
      )
    }

    Update the Main Page to Require Auth​

    We don't want users who are not logged in to access the main page, because they won't be able to create any tasks. So let's make the page private by requiring the user to be logged in:

    main.wasp
    // ...

    page MainPage {
      authRequired: true,
      component: import { MainPage } from "@src/MainPage"
    }

    Now that auth is required for this page, unauthenticated users will be redirected to /login, as we specified with app.auth.onAuthFailedRedirectTo.

    Additionally, when authRequired is true, the page's React component will be provided a user object as prop.

    src/MainPage.jsx
    export const MainPage = ({ user }) => {
      // Do something with the user
      // ...
    }

    Ok, time to test this out. Navigate to the main page (/) of the app. You'll get redirected to /login, where you'll be asked to authenticate.

    Since we just added users, you don't have an account yet. Go to the signup page and create one. You'll be sent back to the main page where you will now be able to see the TODO list!

    Let's check out what the database looks like. Start the Prisma Studio:

    wasp db studio
    Database demonstration - password hashing

    You'll notice that we now have a User entity in the database alongside the Task entity.

    However, you will notice that if you try logging in as different users and creating some tasks, all users share the same tasks. That's because you haven't yet updated the queries and actions to have per-user tasks. Let's do that next.

    You might notice some extra Prisma models like Auth, AuthIdentity and Session that Wasp created for you. You don't need to care about these right now, but if you are curious, you can read more about them here.

    Defining a User-Task Relation​

    First, let's define a one-to-many relation between users and tasks (check the Prisma docs on relations):

    schema.prisma
    // ...

    model User {
      id    Int    @id @default(autoincrement())
      tasks Task[]
    }

    model Task {
      id          Int     @id @default(autoincrement())
      description String
      isDone      Boolean @default(false)
      user        User?   @relation(fields: [userId], references: [id])
      userId      Int?
    }

    As always, you must migrate the database after changing the Entities:

    wasp db migrate-dev
    note

    We made user and userId in Task optional (via ?) because that allows us to keep the existing tasks, which don't have a user assigned, in the database.

    This isn't recommended because it allows an unwanted state in the database (what is the purpose of the task not belonging to anybody?) and normally we would not make these fields optional.

    Instead, we would do a data migration to take care of those tasks, even if it means just deleting them all. However, for this tutorial, for the sake of simplicity, we will stick with this.

    Updating Operations to Check Authentication​

    Next, let's update the queries and actions to forbid access to non-authenticated users and to operate only on the currently logged-in user's tasks:

    src/queries.js
    import { HttpError } from 'wasp/server'

    export const getTasks = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.findMany({
        where: { user: { id: context.user.id } },
        orderBy: { id: 'asc' },
      })
    }
    src/actions.js
    import { HttpError } from 'wasp/server'

    export const createTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.create({
        data: {
          description: args.description,
          user: { connect: { id: context.user.id } },
        },
      })
    }

    export const updateTask = async (args, context) => {
      if (!context.user) {
        throw new HttpError(401)
      }
      return context.entities.Task.updateMany({
        where: { id: args.id, user: { id: context.user.id } },
        data: { isDone: args.isDone },
      })
    }
    note

    Due to how Prisma works, we had to convert update to updateMany in updateTask action to be able to specify the user id in where.

    With these changes, each user should have a list of tasks that only they can see and edit.

    Try playing around, adding a few users and some tasks for each of them. Then open the DB studio:

    wasp db studio
    Database demonstration

    You will see that each user has their tasks, just as we specified in our code!

    Logout Button​

    Last, but not least, let's add the logout functionality:

    src/MainPage.jsx
    // ...
    import { logout } from 'wasp/client/auth'
    //...

    const MainPage = () => {
      // ...
      return (
        <div>
          // ...
          <button onClick={logout}>Logout</button>
        </div>
      )
    }

    This is it, we have a working authentication system, and our Todo app is multi-user!

    What's Next?​

    We did it 🎉 You've followed along with this tutorial to create a basic Todo app with Wasp.

    You should be ready to learn about more complicated features and go more in-depth with the features already covered. Scroll through the sidebar on the left side of the page to see every feature Wasp has to offer. Or, let your imagination run wild and start building your app! ✨

    Looking for inspiration?

    note

    If you notice that some of the features you'd like to have are missing, or have any other kind of feedback, please write to us on Discord or create an issue on Github, so we can learn which features to add/improve next 🙏

    If you would like to contribute or help to build a feature, let us know! You can find more details on contributing here.

    Oh, and do subscribe to our newsletter! We usually send one per month, and Matija does his best to unleash his creativity to make them engaging and fun to read :D!

    - - + + \ No newline at end of file diff --git a/docs/tutorial/create.html b/docs/tutorial/create.html index b30a073381..fe3800242a 100644 --- a/docs/tutorial/create.html +++ b/docs/tutorial/create.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.15.0

    1. Creating a New Project

    info

    You'll need to have the latest version of Wasp installed locally to follow this tutorial. If you haven't installed it yet, check out the QuickStart guide!

    In this section, we'll guide you through the process of creating a simple Todo app with Wasp. In the process, we'll take you through the most important and useful features of Wasp.

    How Todo App will work once it is done

    If you get stuck at any point (or just want to chat), reach out to us on Discord and we will help you!

    You can find the complete code of the app we're about to build here.

    Creating a Project​

    To setup a new Wasp project, run the following command in your terminal

    $ wasp new TodoApp

    Enter the newly created directory and start the development server:

    $ cd TodoApp
    $ wasp start

    wasp start will take a bit of time to start the server the first time you run it in a new project.

    You will see log messages from the client, server, and database setting themselves up. When everything is ready, a new tab should open in your browser at http://localhost:3000 with a simple placeholder page:

    Screenshot of new Wasp app

    Wasp has generated for you the full front-end and back-end code of the app! Next, we'll take a closer look at how the project is structured.

    A note on supported languages​

    Wasp supports both JavaScript and TypeScript out of the box, but you are free to choose between or mix JavaScript and TypeScript as you see fit.

    We'll provide you with both JavaScript and TypeScript code in this tutorial. Code blocks will have a toggle to switch between vanilla JavaScript and TypeScript.

    Try it out:

    Welcome to JavaScript!

    You are now reading the JavaScript version of the docs. The site will remember your preference as you switch pages.

    You'll have a chance to change the language on every code snippet - both the snippets and the text will update accordingly.

    - - + + \ No newline at end of file diff --git a/docs/tutorial/entities.html b/docs/tutorial/entities.html index 0a67698be5..e0642063a2 100644 --- a/docs/tutorial/entities.html +++ b/docs/tutorial/entities.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    4. Database Entities

    Entities are one of the most important concepts in Wasp and are how you define what gets stored in the database.

    Wasp uses Prisma to talk to the database, and you define Entities by defining Prisma models in the schema.prisma file.

    Since our Todo app is all about tasks, we'll define a Task entity by adding a Task model in the schema.prisma file:

    schema.prisma
    // ...

    model Task {
        id          Int     @id @default(autoincrement())
        description String
        isDone      Boolean @default(false)
    }
    note

    Read more about how Wasp Entities work in the Entities section or how Wasp uses the schema.prisma file in the Prisma Schema File section.

    To update the database schema to include this entity, stop the wasp start process, if it's running, and run:

    wasp db migrate-dev

    You'll need to do this any time you change an entity's definition. It instructs Prisma to create a new database migration and apply it to the database.

    To take a look at the database and the new Task entity, run:

    wasp db studio

    This will open a new page in your browser to view and edit the data in your database.

    Todo App - Db studio showing Task schema

    Click on the Task entity and check out its fields! We don't have any data in our database yet, but we are about to change that.

    - - + + \ No newline at end of file diff --git a/docs/tutorial/pages.html b/docs/tutorial/pages.html index f722971b6f..924e07346c 100644 --- a/docs/tutorial/pages.html +++ b/docs/tutorial/pages.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.15.0

    3. Pages & Routes

    In the default main.wasp file created by wasp new, there is a page and a route declaration:

    main.wasp
    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      // We specify that the React implementation of the page is exported from
      // `src/MainPage.jsx`. This statement uses standard JS import syntax.
      // Use `@src` to reference files inside the `src` folder.
      component: import { MainPage } from "@src/MainPage"
    }

    Together, these declarations tell Wasp that when a user navigates to /, it should render the named export from src/MainPage.tsx.

    The MainPage Component​

    Let's take a look at the React component referenced by the page declaration:

    src/MainPage.jsx
    import waspLogo from './waspLogo.png'
    import './Main.css'

    export const MainPage = () => {
      // ...
    }

    This is a regular functional React component. It also uses the CSS file and a logo image that sit next to it in the src folder.

    That is all the code you need! Wasp takes care of everything else necessary to define, build, and run the web app.

    Keep Wasp start running

    wasp start automatically picks up the changes you make, regenerates the code, and restarts the app. So keep it running in the background.

    It also improves your experience by tracking the working directory and ensuring the generated code/types are up to date with your changes.

    Adding a Second Page​

    To add more pages, you can create another set of page and route declarations. You can even add parameters to the URL path, using the same syntax as React Router. Let's test this out by adding a new page:

    main.wasp
    route HelloRoute { path: "/hello/:name", to: HelloPage }
    page HelloPage {
      component: import { HelloPage } from "@src/HelloPage"
    }

    When a user visits /hello/their-name, Wasp renders the component exported from src/HelloPage.tsx and you can use the useParams hook from react-router-dom to access the name parameter:

    src/HelloPage.jsx
    import { useParams } from 'react-router-dom'

    export const HelloPage = () => {
      const { name } = useParams()
      return <div>Here's {name}!</div>
    }

    Now you can visit /hello/johnny and see "Here's johnny!"

    Cleaning Up​

    Now that you've seen how Wasp deals with Routes and Pages, it's finally time to build the Todo app.

    Start by cleaning up the starter project and removing unnecessary code and files.

    First, remove most of the code from the MainPage component:

    src/MainPage.jsx
    export const MainPage = () => {
      return <div>Hello world!</div>
    }

    At this point, the main page should look like this:

    Todo App - Hello World

    You can now delete redundant files: src/Main.css, src/waspLogo.png, and src/HelloPage.tsx (we won't need this page for the rest of the tutorial).

    Since src/HelloPage.tsx no longer exists, remove its route and page declarations from the main.wasp file.

    Your Wasp file should now look like this:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.15.0"
      },
      title: "TodoApp"
    }

    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      component: import { MainPage } from "@src/MainPage"
    }

    Excellent work!

    You now have a basic understanding of Wasp and are ready to start building your TodoApp. We'll implement the app's core features in the following sections.

    - - + + \ No newline at end of file diff --git a/docs/tutorial/project-structure.html b/docs/tutorial/project-structure.html index 54b3966fb5..8238951823 100644 --- a/docs/tutorial/project-structure.html +++ b/docs/tutorial/project-structure.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -30,7 +30,7 @@ We'll keep it simple by placing everything in the root src directory.

    Many other files (e.g., tsconfig.json, vite-env.d.ts, .wasproot, etc.) help Wasp and the IDE improve your development experience with autocompletion, IntelliSense, and error reporting.

    The vite.config.ts file is used to configure Vite, Wasp's build tool of choice. We won't be configuring Vite in this tutorial, so you can safely ignore the file. Still, if you ever end up wanting more control over Vite, you'll find everything you need to know in custom Vite config docs.

    The schema.prisma file is where you define your database schema using Prisma. We'll cover this a bit later in the tutorial.

    The most important file in the project is main.wasp. Wasp uses the configuration within it to perform its magic. Based on what you write, it generates a bunch of code for your database, server-client communication, React routing, and more.

    Let's take a closer look at main.wasp

    main.wasp​

    main.wasp is your app's definition file. It defines the app's central components and helps Wasp to do a lot of the legwork for you.

    Wasp TS config [Early-preview feature]

    If you wish, you can alternatively define your Wasp config in TS (main.wasp.ts) instead of main.wasp.

    The file is a list of declarations. Each declaration defines a part of your app.

    The default main.wasp file generated with wasp new on the previous page looks like this:

    main.wasp
    app TodoApp {
      wasp: {
        version: "^0.15.0" // Pins the version of Wasp to use.
      },
      title: "TodoApp" // Used as the browser tab title. Note that all strings in Wasp are double quoted!
    }

    route RootRoute { path: "/", to: MainPage }
    page MainPage {
      // We specify that the React implementation of the page is exported from
      // `src/MainPage.jsx`. This statement uses standard JS import syntax.
      // Use `@src` to reference files inside the `src` folder.
      component: import { MainPage } from "@src/MainPage"
    }

    This file uses three declaration types:

    • app: Top-level configuration information about your app.

    • route: Describes which path each page should be accessible from.

    • page: Defines a web page and the React component that gets rendered when the page is loaded.

    In the next section, we'll explore how route and page work together to build your web app.

    - - + + \ No newline at end of file diff --git a/docs/tutorial/queries.html b/docs/tutorial/queries.html index cb58fd04d4..9b5f3c2d84 100644 --- a/docs/tutorial/queries.html +++ b/docs/tutorial/queries.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    5. Querying the Database

    We want to know which tasks we need to do, so let's list them!

    The primary way of working with Entities in Wasp is with Queries and Actions, collectively known as Operations.

    Queries are used to read an entity, while Actions are used to create, modify, and delete entities. Since we want to list the tasks, we'll want to use a Query.

    To list the tasks, you must:

    1. Create a Query that fetches the tasks from the database.
    2. Update the MainPage.tsx to use that Query and display the results.

    Defining the Query​

    We'll create a new Query called getTasks. We'll need to declare the Query in the Wasp file and write its implementation in .

    Declaring a Query​

    We need to add a query declaration to main.wasp so that Wasp knows it exists:

    main.wasp
    // ...

    query getTasks {
      // Specifies where the implementation for the query function is.
      // The path `@src/queries` resolves to `src/queries.js`.
      // No need to specify an extension.
      fn: import { getTasks } from "@src/queries",
      // Tell Wasp that this query reads from the `Task` entity. Wasp will
      // automatically update the results of this query when tasks are modified.
      entities: [Task]
    }

    Implementing a Query​

    src/queries.js
    export const getTasks = async (args, context) => {
      return context.entities.Task.findMany({
        orderBy: { id: 'asc' },
      })
    }

    Query function parameters:

    • args: object

      The arguments the caller passes to the Query.

    • context

      An object with extra information injected by Wasp. Its type depends on the Query declaration.

    Since the Query declaration in main.wasp says that the getTasks Query uses Task entity, Wasp injected a Prisma client for the Task entity as context.entities.Task - we used it above to fetch all the tasks from the database.

    info

    Queries and Actions are NodeJS functions executed on the server.

    Invoking the Query On the Frontend​

    While we implement Queries on the server, Wasp generates client-side functions that automatically take care of serialization, network calls, and cache invalidation, allowing you to call the server code like it's a regular function.

    This makes it easy for us to use the getTasks Query we just created in our React component:

    src/MainPage.jsx
    import { getTasks, useQuery } from 'wasp/client/operations'

    export const MainPage = () => {
      const { data: tasks, isLoading, error } = useQuery(getTasks)

      return (
        <div>
          {tasks && <TasksList tasks={tasks} />}

          {isLoading && 'Loading...'}
          {error && 'Error: ' + error}
        </div>
      )
    }

    const TaskView = ({ task }) => {
      return (
        <div>
          <input type="checkbox" id={String(task.id)} checked={task.isDone} />
          {task.description}
        </div>
      )
    }

    const TasksList = ({ tasks }) => {
      if (!tasks?.length) return <div>No tasks</div>

      return (
        <div>
          {tasks.map((task, idx) => (
            <TaskView task={task} key={idx} />
          ))}
        </div>
      )
    }

    Most of this code is regular React, the only exception being the special wasp imports:

    We could have called the Query directly using getTasks(), but the useQuery hook makes it reactive: React will re-render the component every time the Query changes. Remember that Wasp automatically refreshes Queries whenever the data is modified.

    With these changes, you should be seeing the text "No tasks" on the screen:

    Todo App - No Tasks

    We'll create a form to add tasks in the next step 🪄

    - - + + \ No newline at end of file diff --git a/docs/vision.html b/docs/vision.html index 4cdc22aaeb..cf60738b78 100644 --- a/docs/vision.html +++ b/docs/vision.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -33,7 +33,7 @@ They can be used inline (mixed with Wasp code) or provided via external files.
  • Has hatches (escape mechanisms) that allow you to customize your web app in all the right places, but remain hidden until you need them.
  • Entity (data model) is a first-class citizen - defined via custom Wasp syntax and it integrates very closely with the rest of the features, serving as one of the central concepts around which everything is built.
  • Out of the box support for CRUD UI based on the Entities, to get you quickly going, but also customizable to some level.
  • "Smart" operations (queries and actions) that in most cases automatically figure out when to update, and if not it is easy to define custom logic to compensate for that. User worries about client-server gap as little as possible.
  • Support, directly in Wasp, for declaratively defining simple components and operations.
  • Besides Wasp as a programming language, there will also be a visual builder that generates/edits Wasp code, allowing non-developers to participate in development. Since Wasp is declarative, we imagine such builder to naturally follow from Wasp language.
  • Server side rendering, caching, packaging, security, ... -> all those are taken care of by Wasp. You tell Wasp what you want, and Wasp figures out how to do it.
  • As simple deployment to production/staging as it gets.
  • While it comes with the official implementation(s), Wasp language will not be coupled with the single implementation. Others can provide implementations that compile to different web app stacks.
    • - - + + \ No newline at end of file diff --git a/docs/wasp-ai/creating-new-app.html b/docs/wasp-ai/creating-new-app.html index 56f2527bfe..d19b5f0918 100644 --- a/docs/wasp-ai/creating-new-app.html +++ b/docs/wasp-ai/creating-new-app.html @@ -18,15 +18,15 @@ - - - + + +
    Version: 0.15.0

    Creating New App with AI

    Wasp comes with its own AI: Wasp AI, aka Mage (Magic web App GEnerator).

    Wasp AI allows you to create a new Wasp app from only a title and a short description (using GPT in the background)!

    There are two main ways to create a new Wasp app with Wasp AI:

    1. Free, open-source online app usemage.ai.
    2. Running wasp new on your machine and picking AI generation. For this you need to provide your own OpenAI API keys, but it allows for more flexibility (choosing GPT models).

    They both use the same logic in the background, so both approaches are equally "smart", the difference is just in the UI / settings.

    info

    Wasp AI is an experimental feature. Apps that Wasp AI generates can have mistakes (proportional to their complexity), but even then they can often serve as a great starting point (once you fix the mistakes) or an interesting way to explore how to implement stuff in Wasp.

    usemage.ai​

    1. Describe your app 2. Pick the color 3. Generate your app 🚀

    Mage is an open-source app with which you can create new Wasp apps from just a short title and description.

    It is completely free for you - it uses our OpenAI API keys and we take on the costs.

    Once you provide an app title, app description, and choose some basic settings, your new Wasp app will be created for you in a matter of minutes and you will be able to download it to your machine and keep working on it!

    If you want to know more, check this blog post for more details on how Mage works, or this blog post for a high-level overview of how we implemented it.

    Wasp CLI​

    You can create a new Wasp app using Wasp AI by running wasp new in your terminal and picking AI generation.

    If you don't have them set yet, wasp will ask you to provide (via ENV vars) your OpenAI API keys (which it will use to query GPT).

    Then, after providing a title and description for your Wasp app, the new app will be generated on your disk!

    wasp-cli-ai-input wasp-cli-ai-generation

    - - + + \ No newline at end of file diff --git a/docs/wasp-ai/developing-existing-app.html b/docs/wasp-ai/developing-existing-app.html index 13f34e32c2..3ed5f15b51 100644 --- a/docs/wasp-ai/developing-existing-app.html +++ b/docs/wasp-ai/developing-existing-app.html @@ -18,14 +18,14 @@ - - - + + +
    Version: 0.15.0

    Developing Existing App with AI

    While Wasp AI doesn't at the moment offer any additional help for developing your Wasp app with AI beyond initial generation, this is something we are exploring actively.

    In the meantime, while waiting for Wasp AI to add support for this, we suggest checking out aider, which is an AI pair programming tool in your terminal. This is a third-party tool, not affiliated with Wasp in any way, but we and some of Wasp users have found that it can be helpful when working on Wasp apps.

    - - + + \ No newline at end of file diff --git a/docs/writingguide.html b/docs/writingguide.html index 004bc7511d..fc45052888 100644 --- a/docs/writingguide.html +++ b/docs/writingguide.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -53,7 +53,7 @@ Many of our titles are currently in title-case, we should start phasing those out.
  • Use the Oxford comma (e.g., "a, b, and c" instead of "a, b and c"). Why the Oxford comma is important

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

    Linking to pages in the docs​

    Always use relative links (e.g. ../../overview.md) to link to other pages, unless you are writing a reusable snippet.

    Never use absolute links starting with /docs because they break our versioned docs, instead use links "absolute to the file root".

    Writing a link "absolute to the file root":

    1. Write an absolute link, start from the file root (e.g. / represents the docs folder)
    2. Include the extension (e.g. .md)

    For example, /docs/introduction should be written as /introduction/introduction.md because this file is located at ./docs/introduction/introduction.md.

    Or another example /docs/auth/entities#accessing-the-auth-fields becomes /auth/entities/entities.md#accessing-the-auth-fields. This file is located at ./docs/auth/entities/entities.md.

    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/index.html b/index.html index 62a2bdb646..9514703a12 100644 --- a/index.html +++ b/index.html @@ -18,9 +18,9 @@ - - - + + +
    @@ -61,7 +61,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 985b868a9d..f35e88d3fb 100644 --- a/search.html +++ b/search.html @@ -18,14 +18,14 @@ - - - + + +

    Search the documentation

    - - + + \ No newline at end of file