Are you lost in the woods?
16 | 17 |Are you looking for the tutorials? They've moved here:
18 | 19 |Here are some official assets for linking to the project.
7 | 8 |
12 | 
20 | 
28 | 65 | Please do not claim endorsement of your product or service by RedwoodJS without permission. 66 | 67 |
Last updated 21 June 2021
9 |To view the RedwoodJS Security policy, click here
10 |If you discover a potential security issue, do let us know as soon as possible. We'll quickly work toward a resolution, so please provide us with a reasonable amount of time before disclosure to the public or a third-party.
14 |Contact us at security@redwoodjs.com
16 |Thank you for helping improve Redwood security!
18 |
29 | The day may come when we ask you for a favor...
33 |And that day is today: star us on GitHub!
34 | Star on GitHub 35 |
39 | ...\${text}
38 |No docs found for ${data.query}
` 93 | ) 94 | } 95 | 96 | const sections = [] 97 | data.hits.map((hit) => { 98 | if (sections.indexOf(hit.book) === -1) { 99 | sections.push(hit.book) 100 | } 101 | }) 102 | 103 | const items = {} 104 | data.hits.forEach((hit) => { 105 | let attributes = Object.assign(clone(hit), { 106 | text: this._formatText(hit.text), 107 | section: this._formatSection(hit.section), 108 | }) 109 | let html = this.searchResultTemplate(attributes) 110 | 111 | if (items[hit.book]) { 112 | items[hit.book].push(html) 113 | } else { 114 | items[hit.book] = [html] 115 | } 116 | }) 117 | 118 | let output = '' 119 | for (let item in items) { 120 | output += `
68 | ```
69 |
70 | > Note: because the directory `dist/` becomes your production root, it should not be included in the path.
71 |
--------------------------------------------------------------------------------
/docs/builds.md:
--------------------------------------------------------------------------------
1 | # Builds
2 |
3 | > ⚠ **Work in Progress** ⚠️
4 | >
5 | > There's more to document here. In the meantime, you can check our [community forum](https://community.redwoodjs.com/search?q=yarn%20rw%20build) for answers.
6 | >
7 | > Want to contribute? Redwood welcomes contributions and loves helping people become contributors.
8 | > You can edit this doc [here](https://github.com/redwoodjs/redwoodjs.com/blob/main/docs/builds.md).
9 | > If you have any questions, just ask for help! We're active on the [forums](https://community.redwoodjs.com/c/contributing/9) and on [discord](https://discord.com/channels/679514959968993311/747258086569541703).
10 |
11 |
12 | ## API
13 |
14 | The api side of Redwood is transpiled by Babel into the `./api/dist` folder.
15 |
16 | ### steps on Netlify
17 |
18 | To emulate Netlify's build steps locally:
19 |
20 | ```bash
21 | yarn rw build api
22 | cd api
23 | yarn zip-it-and-ship-it dist/functions/ zipballs/
24 | ```
25 |
26 | Each lambda function in `./api/dist/functions` is parsed by zip-it-and-ship-it resulting in a zip file per lambda function that contains all the dependencies required for that lambda function.
27 |
28 | >Note: The `@netlify/zip-it-and-ship-it` package needs to be installed as a dev dependency in `api/`. Use the command `yarn workspace api add -D @netlify/zip-it-and-ship-it`.
29 | >- You can learn more about the package [here](https://www.npmjs.com/package/@netlify/zip-it-and-ship-it).
30 | >- For more information on AWS Serverless Deploy see these [docs](https://redwoodjs.com/docs/deploy#aws-serverless-deploy).
31 |
32 | ## Web
33 |
34 | The web side of Redwood is packaged by Webpack into the `./web/dist` folder.
35 |
--------------------------------------------------------------------------------
/docs/connectionPooling.md:
--------------------------------------------------------------------------------
1 | # Connection Pooling
2 |
3 | > ⚠ **Work in Progress** ⚠️
4 | >
5 | > There's more to document here. In the meantime, you can check our [community forum](https://community.redwoodjs.com/search?q=connection%20pooling) for answers.
6 | >
7 | > Want to contribute? Redwood welcomes contributions and loves helping people become contributors.
8 | > You can edit this doc [here](https://github.com/redwoodjs/redwoodjs.com/blob/main/docs/connectionPooling.md).
9 | > If you have any questions, just ask for help! We're active on the [forums](https://community.redwoodjs.com/c/contributing/9) and on [discord](https://discord.com/channels/679514959968993311/747258086569541703).
10 |
11 | Production Redwood apps should enable connection pooling in order to properly scale with your Serverless functions.
12 | ## Prisma Pooling with PgBouncer
13 |
14 | PgBouncer holds a connection pool to the database and proxies incoming client connections by sitting between Prisma Client and the database. This reduces the number of processes a database has to handle at any given time. PgBouncer passes on a limited number of connections to the database and queues additional connections for delivery when space becomes available.
15 |
16 |
17 | To use Prisma Client with PgBouncer from a serverless function, add the `?pgbouncer=true` flag to the PostgreSQL connection URL:
18 |
19 | ```
20 | postgresql://USER:PASSWORD@HOST:PORT/DATABASE?pgbouncer=true
21 | ```
22 |
23 | Typically, your PgBouncer port will be 6543 which is different than the Postgres default of 5432.
24 |
25 | > Note that since Prisma Migrate uses database transactions to check out the current state of the database and the migrations table, if you attempt to run Prisma Migrate commands in any environment that uses PgBouncer for connection pooling, you might see an error.
26 | >
27 | > To work around this issue, you must connect directly to the database rather than going through PgBouncer when migrating.
28 |
29 | For more information on Prisma and PgBouncer, please refer to Prisma's Guide on [Configuring Prisma Client with PgBouncer](https://www.prisma.io/docs/guides/performance-and-optimization/connection-management/configure-pg-bouncer).
30 |
31 | ## Supabase
32 |
33 | For Postgres running on [Supabase](https://supabase.io) see: [PgBouncer is now available in Supabase](https://supabase.io/blog/2021/04/02/supabase-pgbouncer#using-connection-pooling-in-supabase).
34 |
35 | All new Supabase projects include connection pooling using [PgBouncer](https://www.pgbouncer.org/).
36 |
37 | We recommend that you connect to your Supabase Postgres instance using SSL which you can do by setting `sslmode` to `require` on the connection string:
38 |
39 | ```
40 | // not pooled typically uses port 5432
41 | postgresql://postgres:mydb.supabase.co:5432/postgres?sslmode=require
42 | // pooled typically uses port 6543
43 | postgresql://postgres:mydb.supabase.co:6543/postgres?sslmode=require&pgbouncer=true
44 | ```
45 |
46 | ## Heroku
47 | For Postgres, see [Postgres Connection Pooling](https://devcenter.heroku.com/articles/postgres-connection-pooling).
48 |
49 | Heroku does not officially support MySQL.
50 |
51 |
52 | ## Digital Ocean
53 | For Postgres, see [How to Manage Connection Pools](https://www.digitalocean.com/docs/databases/postgresql/how-to/manage-connection-pools)
54 |
55 | Connection Pooling for MySQL is not yet supported.
56 |
57 | ## AWS
58 | Use [Amazon RDS Proxy](https://aws.amazon.com/rds/proxy) for MySQL or PostgreSQL.
59 |
60 | From the [AWS Docs](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.html#rds-proxy.limitations):
61 | >Your RDS Proxy must be in the same VPC as the database. The proxy can't be publicly accessible.
62 |
63 | Because of this limitation, with out-of-the-box configuration, you can only use RDS Proxy if you're deploying your Lambda Functions to the same AWS account. Alternatively, you can use RDS directly, but you might require larger instances to handle your production traffic and the number of concurrent connections.
64 |
65 |
66 | ## Why Connection Pooling?
67 |
68 | Relational databases have a maximum number of concurrent client connections.
69 |
70 | * Postgres allows 100 by default
71 | * MySQL allows 151 by default
72 |
73 | In a traditional server environment, you would need a large amount of traffic (and therefore web servers) to exhaust these connections, since each web server instance typically leverages a single connection.
74 |
75 | In a Serverless environment, each function connects directly to the database, which can exhaust limits quickly. To prevent connection errors, you should add a connection pooling service in front of your database. Think of it as a load balancer.
76 |
--------------------------------------------------------------------------------
/docs/customIndex.md:
--------------------------------------------------------------------------------
1 | # Custom Web Index
2 |
3 | You might've noticed that there's no call to `ReactDOM.render` anywhere in your Redwood App (`v0.26` and greater). That's because Redwood automatically mounts your `
60 |
61 | Redwood has created everything we need to create, edit, delete and view a User. And you didn't have to write one line of boilerplate code.
62 |
63 | We have some other [generators](https://redwoodjs.com/docs/cli-commands#generate-alias-g) that are just as awesome, don't forget to check them out as well.
64 |
65 | ## Next Steps
66 |
67 | Need more? The best way to get to know Redwood is by going through the extensive [Redwood Tutorial](https://redwoodjs.com/tutorial/welcome-to-redwood).
68 |
69 | - Join our [Discord Server](https://discord.gg/redwoodjs)
70 | - Join our [Discourse Community](https://community.redwoodjs.com)
71 |
--------------------------------------------------------------------------------
/docs/schemaRelations.md:
--------------------------------------------------------------------------------
1 | # Prisma Relations and Redwood's Generators
2 |
3 | These docs apply to Redwood v0.25 and greater. Previous versions of Redwood had limitations when creating scaffolds for any one-to-many or many-to-many relationships. Most of those have been resolved so you should definitely [upgrade to 0.25](https://community.redwoodjs.com/t/upgrading-to-redwoodjs-v0-25-and-prisma-v2-16-db-upgrades-and-project-code-mods/1811) if at all possible!
4 |
5 | ## Many-to-many Relationships
6 |
7 | [Here](https://www.prisma.io/docs/concepts/components/prisma-schema/relations#many-to-many-relations)
8 | are Prisma's docs for creating many-to-many relationships - A many-to-many
9 | relationship is accomplished by creating a "join" or "lookup" table between two
10 | other tables. For example, if a **Product** can have many **Tag**s, any given
11 | **Tag** can also have many **Product**s that it is attached to. A database
12 | diagram for this relationship could look like:
13 |
14 | ```
15 | ┌───────────┐ ┌─────────────────┐ ┌───────────┐
16 | │ Product │ │ ProductsOnTag │ │ Tag │
17 | ├───────────┤ ├─────────────────┤ ├───────────┤
18 | │ id │────<│ productId │ ┌──│ id │
19 | │ title │ │ tagId │>──┘ │ name │
20 | │ desc │ └─────────────────┘ └───────────┘
21 | └───────────┘
22 | ```
23 |
24 | The `schema.prisma` syntax to create this relationship looks like:
25 |
26 | ```javascript
27 | model Product {
28 | id Int @id @default(autoincrement())
29 | title String
30 | desc String
31 | tags Tag[]
32 | }
33 |
34 | model Tag {
35 | id Int @id @default(autoincrement())
36 | name String
37 | products Product[]
38 | }
39 | ```
40 |
41 | These relationships can be [implicit](https://www.prisma.io/docs/concepts/components/prisma-schema/relations#implicit-many-to-many-relations) (as this diagram shows) or [explicit](https://www.prisma.io/docs/concepts/components/prisma-schema/relations#explicit-many-to-many-relations) (explained below). Redwood's SDL generator (which is also used by the scaffold generator) only supports an **explicit** many-to-many relationship when generating with the `--crud` flag. What's up with that?
42 |
43 | ## CRUD Requires an `@id`
44 |
45 | CRUD (Create, Retrieve, Update, Delete) actions in Redwood currently require a single, unique field in order to retrieve, update or delete a record. This field must be denoted with Prisma's [`@id`](https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference#id) attribute, marking it as the tables's primary key. This field is guaranteed to be unique and so can be used to find a specific record.
46 |
47 | Prisma's implicit many-to-many relationships create a table _without_ a single field marked with the `@id` attribute. Instead, it uses a similar attribute: [`@@id`](https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference#id-1) to define a *multi-field ID*. This multi-field ID will become the tables's primary key. The diagram above shows the result of letting Prisma create an implicit relationship.
48 |
49 | Since there's no single `@id` field in implicit many-to-many relationships, you can't use the SDL generator with the `--crud` flag. Likewise, you can't use the scaffold generator, which uses the SDL generator (with `--crud`) behind the scenes.
50 |
51 | ## Supported Table Structure
52 |
53 | To support both CRUD actions and to remain consistent with Prisma's many-to-many relationships, a combination of the `@id` and [`@@unique`](https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference#unique-1) attributes can be used. With this, `@id` is used to create a primary key on the lookup-table; and `@@unique` is used to maintain the table's unique index, which was previously accomplished by the primary key created with `@@id`.
54 |
55 | > Removing `@@unique` would let a specific **Product** reference a particular **Tag** more than a single time.
56 |
57 | You can get this working by creating an explicit relationship—defining the table structure yourself:
58 |
59 | ```javascript
60 | model Product {
61 | id Int @id @default(autoincrement())
62 | title String
63 | desc String
64 | tags ProductsOnTag[]
65 | }
66 |
67 | model Tag {
68 | id Int @id @default(autoincrement())
69 | name String
70 | products ProductsOnTag[]
71 | }
72 |
73 | model ProductsOnTag {
74 | id Int @id @default(autoincrement())
75 | tagId Int
76 | tag Tag @relation(fields: [tagId], references: [id])
77 | productId Int
78 | product Product @relation(fields: [productId], references: [id])
79 |
80 | @@unique([tagId, productId])
81 | }
82 | ```
83 |
84 | Which creates a table structure like:
85 |
86 | ```
87 | ┌───────────┐ ┌──────────────────┐ ┌───────────┐
88 | │ Product │ │ ProductsOnTags │ │ Tag │
89 | ├───────────┤ ├──────────────────┤ ├───────────┤
90 | │ id │──┐ │ id │ ┌──│ id │
91 | │ title │ └──<│ productId │ │ │ name │
92 | │ desc │ │ tagId │>─┘ └───────────┘
93 | └───────────┘ └──────────────────┘
94 |
95 | ```
96 |
97 | Almost identical! But now there's an `id` and the SDL/scaffold generators will work as expected. The explicit syntax gives you a couple additional benefits—you can customize the table name and even add more fields. Maybe you want to track which user tagged a product—add a `userId` column to `ProductsOnTags` and now you know.
98 |
--------------------------------------------------------------------------------
/docs/security.md:
--------------------------------------------------------------------------------
1 | # Security
2 |
3 | RedwoodJS wants you to be able build and deploy secure applications and takes the topic of security seriously.
4 |
5 | * [RedwoodJS Security](https://github.com/redwoodjs/redwood/security) on GitHub
6 | * [CodeQL code scanning](https://github.com/features/security)
7 | * [Authentication](/docs/authentication)
8 | * [Webhook signature verification](/docs/webhooks)
9 | * [Ways to keep your serverless functions secure](/docs/serverless-functions#security-considerations)
10 | * [Environment variables for secure keys and tokens](/docs/environment-variables)
11 |
12 | > ⚠️ **Security is Your Responsibility**
13 | > While Redwood offers the tools, practices, and information to keep your application secure, it remains your responsibility to put these in place. Proper password, token, and key protection using disciplined communication, password management systems, and environment management services like [Doppler](https://www.doppler.com) are strongly encouraged.
14 |
15 | > **Security Policy and Contact Information**
16 | > The RedwoodJS Security Policy is located [in the codebase repository on GitHub](https://github.com/redwoodjs/redwood/security/policy)
17 | >
18 | > To report a potential security vulnerability, contact us at [security@redwoodjs.com](mailto:security@redwoodjs.com)
19 | ## Authentication
20 |
21 | `@redwoodjs/auth` is a lightweight wrapper around popular SPA authentication libraries. We [currently support](https://redwoodjs.com/docs/authentication) the following authentication providers:
22 |
23 | * Netlify Identity Widget
24 | * Auth0
25 | * Azure Active Directory
26 | * Netlify GoTrue-JS
27 | * Magic Links - Magic.js
28 | * Firebase's GoogleAuthProvider
29 | * Ethereum
30 | * Supabase
31 | * Nhost
32 |
33 | For example implementations, please see [Authentication](https://github.com/redwoodjs/redwood/tree/main/packages/auth) and the use of the `getCurrentUser` and `requireAuth` helpers.
34 |
35 | For a demonstration, check out the [Auth Playground](https://redwood-playground-auth.netlify.app).
36 |
37 | ## GraphQL
38 |
39 | GraphQL is a fundamental part of Redwood. For details on how Redwood uses GraphQL and handles important security considerations, please see the [GraphQL Security](/docs/graphql.html#security) section and the [Secure Services](/docs/services.html#secure-services) section.
40 |
41 | ### Depth Limits
42 |
43 | The RedwoodJS GraphQL handler sets [reasonable defaults](/docs/graphql.html##query-depth-limit) to prevent deep, cyclical nested queries that attackers often use to exploit systems.
44 | ### Disable Introspection and Playground
45 |
46 | Because both introspection and the playground share possibly sensitive information about your data model, your data, your queries and mutations, best practices for deploying a GraphQL Server call to [disable these in production](/docs/graphql.html#introspection-and-playground-disabled-in-production), RedwoodJS **only enables introspection and the playground when running in development**.
47 | ## Functions
48 |
49 | When deployed, a [serverless function](/docs/serverless-functions) is an open API endpoint. That means anyone can access it and perform any tasks it's asked to do. In many cases, this is completely appropriate and desired behavior. But there are often times you need to restrict access to a function, and Redwood can help you do that using a [variety of methods and approaches](/docs/serverless-functions#security-considerations).
50 |
51 | For details on how to keep your functions secure, please see the [Serverless functions & Security considerations](/docs/serverless-functions#security-considerations) section in the RedwoodJS documentation.
52 |
53 | ## Webhooks
54 |
55 | [Webhooks](/docs/webhooks) are a common way that third-party services notify your RedwoodJS application when an event of interest happens.
56 |
57 | They are a form of messaging or automation and allows web applications to communicate with each other and send real-time data from one application to another whenever a given event occurs.
58 |
59 | Since each of these webhooks will call a function endpoint in your RedwoodJS api, you need to ensure that these run **only when they should**. That means you need to:
60 |
61 | * Verify it comes from the place you expect
62 | * Trust the party
63 | * Know the payload sent in the hook hasn't been tampered with
64 | * Ensure that the hook isn't reprocessed or replayed
65 |
66 | For details on how to keep your incoming webhooks secure and how to sign your outgoing webhooks, please see [Webhooks](/docs/webhooks).
67 |
--------------------------------------------------------------------------------
/docs/seo.md:
--------------------------------------------------------------------------------
1 | # SEO & Meta tags
2 |
3 | ## Add app title
4 | You certainly want to change the title of your Redwood app.
5 | You can start by adding or modify `title` inside `redwood.toml`
6 |
7 | ```diff
8 | [web]
9 | - title = "Redwood App"
10 | + title = "My Cool App"
11 | port = 8910
12 | apiUrl = "/.redwood/functions"
13 | ```
14 | This title (the app title) is used by default for all your pages if you don't define another one.
15 | It will also be use for the title template !
16 | ### Title template
17 | Now that you have the app title set, you probably want some consistence with the page title, that's what the title template is for.
18 |
19 | Add `titleTemplate` as a prop for `RedwoodProvider` to have a title template for every pages
20 |
21 | In _web/src/App.{tsx,js}_
22 | ```diff
23 | - This is the about page!
98 |All the news that's fit to print about RedwoodJS. If you've got news we should feature open a PR. 7 |
15 | ${description} 16 |
17 |9 |18 | 19 |10 | Out of the box, @RedwoodJS provides automatic 11 | code-splitting and a super easy to use loading state you can show when page loads take longer than a 12 | configurable amount of time (great for slow connections) without any white page flash or annoying shenanigans. 13 | Check the vid for how! pic.twitter.com/c4T0P213dM 14 |
15 | — Tom Preston-Werner (@mojombo) 16 | April 15, 2020 17 |