8 |
9 | #### What is this for?
10 |
11 | This template is for
12 |
13 | - making a React website
14 | - making a React web application with a database
15 |
16 | If you are a beginner and you just want to make a simple React project with no database, try [next-sass](https://github.com/application-research/next-sass).
17 |
18 | #### Why would I use this?
19 |
20 | You want to...
21 |
22 | - use [React](https://reactjs.org/).
23 | - use [SASS](https://sass-lang.com/), like the good old days.
24 | - use [https://nextjs.org/](NextJS) and `dotenv` for things like server side rendering and obfuscating secrets on a server.
25 | - You should never expose client secrets in the browser.
26 | - use Postgres 14 (latest as of June 19th, 2022) to manage local data or local authentication.
27 | - have templated SEO metatags.
28 | - get the minimum code involved to make a production website
29 | - **[OPTIONAL]** start with a [Google Authentication](https://github.com/googleapis/google-api-nodejs-client) example to create.
30 | - start with an example of "organizations", each organization is created with an e-mail's domain name.
31 | - **[OPTIONAL]** authenticate your Ethereum addresses from [Metamask](https://metamask.io/) to build a DAPP or DAO. This example keeps a table of Ethereum addresses where you can store local information in the `jsonb` column.
32 | - You'll need your own strategy for joining your Ethereum address to your local account.
33 | - **[OPTIONAL]** authenticate your Solana address (public key) from [Phantom](https://phantom.app) to build a DAPP or DAO. This example keeps a table of Solana addresses where you can store local information in the `jsonb` column.
34 | - You'll need your own strategy for joining your Solana address to your local account.
35 |
36 | ## Setup (MacOS)
37 |
38 | All steps assume you have
39 |
40 | - installed [Homebrew](https://brew.sh/)
41 | - installed [iTerm](https://iterm2.com/), because you will need multiple terminal windows open.
42 |
43 | #### Step 1
44 |
45 | Clone this repository!
46 |
47 | #### Step 2
48 |
49 | Create an `.env` file in your project root.
50 |
51 | ```sh
52 | JWT_SECRET=74b8b454-29a6-4282-bdec-7e2895c835eb
53 | SERVICE_PASSWORD_SALT=\$2b\$10\$JBb8nz6IIrIXKeySeuY3aO
54 | PASSWORD_ROUNDS=10
55 | ```
56 |
57 | - Generate your own `SERVICE_PASSWORD_SALT` with `BCrypt.genSaltSync(10)`.
58 | - You need to use `\` to escape the `$` values as shown above. Also make sure you're using the correct amount of rounds.
59 | - Generate your own `JWT_SECRET`.
60 |
61 | #### **[OPTIONAL]** Step 3
62 |
63 | To get google auth support to work, add the following to your `.env` file in your project root directory.
64 |
65 | ```sh
66 | GOOGLE_CLIENT_ID=GET_ME_FROM_GOOGLE
67 | GOOGLE_CLIENT_SECRET=GET_ME_FROM_GOOGLE
68 | GOOGLE_REDIRECT_URIS=http://localhost:3005/google-authentication
69 | ```
70 |
71 | - Obtain `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` from [https://console.developers.google.com](https://console.developers.google.com) after you setup your application.
72 | - Enable [People API](https://console.developers.google.com/apis/api/people.googleapis.com/overview). Otherwise Google Auth will not work for this example.
73 | - Use `CMD+F` to find `GOOGLE_REDIRECT_URIS` in `@data/environment`. Google needs this string for the **Authorized redirect URIs** setting. The default is: `http://localhost:3005/google-authentication`.
74 |
75 | #### Step 4
76 |
77 | Install Postgres 14 locally
78 |
79 | ```sh
80 | brew uninstall postgresql
81 | brew install postgresql
82 | brew link postgresql --force
83 | ```
84 |
85 | At the time of writing this (June 19th, 2022), `postgresql` is version 14.
86 |
87 | If you see
88 |
89 | ```sh
90 | # already linked, don't worry, nothing to worry about
91 |
92 | Warning: Already linked: /usr/local/Cellar/postgresql/14.4
93 | To relink, run:
94 | brew unlink postgresql && brew link postgresql
95 |
96 | # run brew postgresql-upgrade-database
97 |
98 | Postgres - FATAL: database files are incompatible with server
99 | ```
100 |
101 | Everything is fine.
102 |
103 | Next make sure NodeJS version 10+ is installed on your machine.
104 |
105 | ```sh
106 | brew install node
107 | ```
108 |
109 | Install dependencies
110 |
111 | ```sh
112 | npm install
113 | npm run dev
114 | ```
115 |
116 | #### Step 5
117 |
118 | Run Postgres 14.
119 |
120 | I prefer the option to start and stop postgres through the command line.
121 | - If you have another way of doing things, just make sure your port is set to `1334`.
122 |
123 | In a seperate terminal tab run
124 |
125 | ```sh
126 | postgres -D /usr/local/var/postgres -p 1334
127 | ```
128 |
129 | Now your development environment is setup.
130 |
131 | #### Step 5
132 |
133 | You need to create a user named `admin` and database named `wwwdb`.
134 |
135 | ```sh
136 | # Enter Postgres console
137 | psql postgres -p 1334
138 |
139 | # Create a new user for yourself
140 | CREATE ROLE admin WITH LOGIN PASSWORD 'oblivion';
141 |
142 | # Allow yourself to create databases
143 | ALTER ROLE admin CREATEDB;
144 |
145 | # You need to do this to install uuid-ossp in a later step
146 | ALTER USER admin WITH SUPERUSER;
147 |
148 | # Exit Postgres console
149 | \q
150 |
151 | # Log in as your new user.
152 | psql postgres -p 1334 -U admin
153 |
154 | # Create a database named: nptdb.
155 | # If you change this, update knexfile.js
156 | CREATE DATABASE wwwdb;
157 |
158 | # Give your self privileges
159 | GRANT ALL PRIVILEGES ON DATABASE wwwdb TO admin;
160 |
161 | # List all of your databases
162 | \list
163 |
164 | # Connect to your newly created DB as a test
165 | \connect wwwdb
166 |
167 | # Exit Postgres console
168 | \q
169 | ```
170 |
171 | #### Step 6
172 |
173 | Setup and install the necessary Postgres plugins. Aftewards seed the database with the necessary tables.
174 |
175 | ```sh
176 | npm run script database-setup
177 | npm run script database-seed
178 | ```
179 |
180 | There is also `npm run script database-drop` if you just want to drop your tables for testing.
181 |
182 | #### **[OPTIONAL]** Step 7
183 |
184 | If you need to run a node script without running the node server, an example is provided for your convenience
185 |
186 | ```sh
187 | npm run script example
188 | ```
189 |
190 | #### Finish
191 |
192 | View `http://localhost:3005` in your browser. You should be able to use the full example end-to-end and modify the code however you like.
193 |
194 | #### Production deployment
195 |
196 | You will need to add production environment variables. If you set up your Postgres database on [Render](https://render.com) the values will look something like this
197 |
198 | ```env
199 | PRODUCTION_DATABASE_PORT=5432
200 | PRODUCTION_DATABASE_HOST=oregon-postgres.render.com
201 | PRODUCTION_DATABASE_NAME=yourdatabasename
202 | PRODUCTION_DATABASE_USERNAME=yourdatabasename_user
203 | PRODUCTION_DATABASE_PASSWORD=XXXXXXXXXXXXXXXXXXXXX
204 | ```
205 |
206 | Then you will need to run production scripts
207 |
208 | ```sh
209 | npm run production-script database-setup
210 | npm run production-script database-seed
211 | ```
212 |
213 | For deploying your new website, I recommend any of the following choices:
214 |
215 | - [Render](https://render.com/i/internet-gift-from-jim)
216 | - [Vercel](https://vercel.com/)
217 | - [Heroku](https://heroku.com)
218 |
219 | #### Questions?
220 |
221 | Contact [@wwwjim](https://twitter.com/wwwjim).
222 |
--------------------------------------------------------------------------------
/common/actions.ts:
--------------------------------------------------------------------------------
1 | import * as Requests from "@common/requests";
2 | import * as Constants from "@common/constants";
3 | import * as Strings from "@common/strings";
4 |
5 | // TODO(jim): Remove this dependency at some point.
6 | import Cookies from "universal-cookie";
7 |
8 | const cookies = new Cookies();
9 |
10 | declare const window: any;
11 |
12 | const signIn = async (body: any) => {
13 | cookies.remove(Constants.SESSION_KEY);
14 | let response = await Requests.post("/api/sign-in", body);
15 | if (response.success) {
16 | if (response.token) {
17 | cookies.set(Constants.SESSION_KEY, response.token);
18 | }
19 |
20 | return window.location.reload();
21 | }
22 |
23 | return alert(response.error);
24 | };
25 |
26 | const signOut = async () => {
27 | const jwt = cookies.get(Constants.SESSION_KEY);
28 | if (jwt) {
29 | cookies.remove(Constants.SESSION_KEY);
30 | return window.location.reload();
31 | }
32 |
33 | return alert("There was no session to sign out of.");
34 | };
35 |
36 | const deleteViewer = async () => {
37 | let response = await Requests.del("/api/viewer/delete");
38 | if (response.success) {
39 | cookies.remove(Constants.SESSION_KEY);
40 | return window.location.reload();
41 | }
42 |
43 | return alert(response.error);
44 | };
45 |
46 | const connectMetamask = async () => {
47 | if (!window.ethereum) {
48 | alert("Metamask is not installed");
49 | }
50 |
51 | // NOTE(jim): Returns an array of ethereum addresses.
52 | const response = await window.ethereum.request({
53 | method: "eth_requestAccounts",
54 | });
55 |
56 | // NOTE(jim): Add a database record to associate centralized data to an address.
57 | if (response && response.length) {
58 | for await (const address of response) {
59 | await Requests.post("/api/ethereum/create", { address });
60 | }
61 | }
62 |
63 | return window.location.reload();
64 | };
65 |
66 | const connectPhantom = async () => {
67 | let address = null;
68 | try {
69 | const response = await window.solana.connect();
70 | address = response.publicKey.toString();
71 | } catch (e) {
72 | console.log(e);
73 | }
74 |
75 | // NOTE(jim): Add a database record to associate centralized data to an address.
76 | if (!Strings.isEmpty(address)) {
77 | await Requests.post("/api/solana/create", { address });
78 | }
79 |
80 | return window.location.reload();
81 | };
82 |
83 | export const execute = async (key: string, body?: any) => {
84 | if (key === "SIGN_IN") return await signIn(body);
85 | if (key === "SIGN_OUT") return await signOut();
86 | if (key === "VIEWER_DELETE_USER") return await deleteViewer();
87 | if (key === "VIEWER_CONNECT_METAMASK") return await connectMetamask();
88 | if (key === "VIEWER_CONNECT_PHANTOM") return await connectPhantom();
89 |
90 | return alert(`There is no action: ${key}`);
91 | };
92 |
--------------------------------------------------------------------------------
/common/constants.ts:
--------------------------------------------------------------------------------
1 | // NOTE(jim): You should change these values to match your service.
2 | export const SESSION_KEY = "DEMO_WEB_SERVICE_SESSION_KEY";
3 | export const SESSION_KEY_REGEX = /(?:(?:^|.*;\s*)DEMO_WEB_SERVICE_SESSION_KEY\s*\=\s*([^;]*).*$)|^.*$/;
4 |
--------------------------------------------------------------------------------
/common/requests.ts:
--------------------------------------------------------------------------------
1 | import * as Constants from "@common/constants";
2 |
3 | // TODO(jim): Remove this dependency at some point.
4 | import Cookies from "universal-cookie";
5 |
6 | const REQUEST_HEADERS = {
7 | Accept: "application/json",
8 | "Content-Type": "application/json",
9 | };
10 |
11 | const cookies = new Cookies();
12 |
13 | const getHeaders = () => {
14 | const jwt = cookies.get(Constants.SESSION_KEY);
15 |
16 | if (jwt) {
17 | return {
18 | ...REQUEST_HEADERS,
19 | authorization: `Bearer ${jwt}`,
20 | };
21 | }
22 |
23 | return REQUEST_HEADERS;
24 | };
25 |
26 | export async function get(route: string, options = {}) {
27 | try {
28 | const response = await fetch(route, {
29 | method: "GET",
30 | headers: getHeaders(),
31 | });
32 |
33 | const json = await response.json();
34 | console.log(route, json);
35 | return json;
36 | } catch (e) {
37 | console.log(e);
38 | return {
39 | error: "REQUEST_FAILED",
40 | };
41 | }
42 | }
43 |
44 | export async function post(route: string, options = {}) {
45 | try {
46 | const response = await fetch(route, {
47 | method: "POST",
48 | headers: getHeaders(),
49 | body: JSON.stringify(options),
50 | });
51 |
52 | const json = await response.json();
53 | console.log(route, json);
54 | return json;
55 | } catch (e) {
56 | console.log(e);
57 | return {
58 | error: "REQUEST_FAILED",
59 | };
60 | }
61 | }
62 |
63 | export async function del(route: string, options = {}) {
64 | try {
65 | const response = await fetch(route, {
66 | method: "DELETE",
67 | headers: getHeaders(),
68 | body: JSON.stringify(options),
69 | });
70 |
71 | const json = await response.json();
72 | console.log(route, json);
73 | return json;
74 | } catch (e) {
75 | console.log(e);
76 | return {
77 | error: "REQUEST_FAILED",
78 | };
79 | }
80 | }
81 |
--------------------------------------------------------------------------------
/common/server.ts:
--------------------------------------------------------------------------------
1 | import Cors from "@modules/cors";
2 |
3 | export function initMiddleware(middleware) {
4 | return (req, res) =>
5 | new Promise((resolve, reject) => {
6 | middleware(req, res, (result) => {
7 | if (result instanceof Error) {
8 | return reject(result);
9 | }
10 | return resolve(result);
11 | });
12 | });
13 | }
14 |
15 | export const cors = initMiddleware(
16 | Cors({
17 | methods: ["GET", "POST", "OPTIONS"],
18 | })
19 | );
20 |
--------------------------------------------------------------------------------
/common/strings.ts:
--------------------------------------------------------------------------------
1 | export const isEmpty = (string: any) => {
2 | return !string || !string.toString().trim();
3 | };
4 |
5 | export const pluralize = (text, count) => {
6 | return count > 1 || count === 0 ? `${text}s` : text;
7 | };
8 |
9 | export const getDomainFromEmail = (email: string): string => {
10 | return email.replace(/.*@/, "");
11 | };
12 |
13 | export const capitalizeFirstLetter = (word: string): string => {
14 | return word.charAt(0).toUpperCase() + word.substring(1);
15 | };
16 |
17 | export const elide = (text, length = 140, emptyState = "...") => {
18 | if (isEmpty(text)) {
19 | return emptyState;
20 | }
21 |
22 | if (text.length < length) {
23 | return text.trim();
24 | }
25 |
26 | return `${text.substring(0, length)}...`;
27 | };
28 |
29 | export const toDate = (data) => {
30 | const date = new Date(data);
31 | return `${date.getMonth() + 1}-${date.getDate()}-${date.getFullYear()}`;
32 | };
33 |
34 | export const toDateISO = (data: string): string => {
35 | const date = new Date(data);
36 | return date.toLocaleDateString("en-US", {
37 | weekday: "long",
38 | day: "numeric",
39 | month: "long",
40 | year: "numeric",
41 | hour12: true,
42 | hour: "numeric",
43 | minute: "2-digit",
44 | second: "2-digit",
45 | });
46 | };
47 |
48 | export const bytesToSize = (bytes: number, decimals: number = 2): string => {
49 | if (bytes === 0) return "0 Bytes";
50 |
51 | const k = 1024;
52 | const dm = decimals < 0 ? 0 : decimals;
53 | const sizes = ["B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"];
54 |
55 | const i = Math.floor(Math.log(bytes) / Math.log(k));
56 |
57 | return `${(bytes / Math.pow(k, i)).toFixed(dm)} ${sizes[i]}`;
58 | };
59 |
--------------------------------------------------------------------------------
/common/utilities-authentication.ts:
--------------------------------------------------------------------------------
1 | import * as Constants from "@common/constants";
2 | import * as Strings from "@common/strings";
3 |
4 | export const getToken = (req) => {
5 | if (Strings.isEmpty(req.headers.cookie)) {
6 | return null;
7 | }
8 |
9 | return req.headers.cookie.replace(Constants.SESSION_KEY_REGEX, "$1");
10 | };
11 |
12 | export const parseAuthHeader = (value) => {
13 | if (typeof value !== "string") {
14 | return null;
15 | }
16 |
17 | var matches = value.match(/(\S+)\s+(\S+)/);
18 | return matches && { scheme: matches[1], value: matches[2] };
19 | };
20 |
--------------------------------------------------------------------------------
/common/utilities.ts:
--------------------------------------------------------------------------------
1 | declare const window: any;
2 |
3 | const hasOwn = {}.hasOwnProperty;
4 |
5 | export async function getWalletStatus() {
6 | const isMetamaskEnabled =
7 | typeof window.ethereum !== "undefined" && window.ethereum.isMetaMask;
8 | const isPhantomEnabled =
9 | typeof window.solana !== "undefined" && window.solana.isPhantom;
10 |
11 | // NOTE(jim): This allows you to get the public key.
12 | if (isPhantomEnabled && !window.solana.publicKey) {
13 | try {
14 | await window.solana.connect({ onlyIfTrusted: true });
15 | } catch (e) {
16 | console.log(e);
17 | }
18 | }
19 |
20 | return { isMetamaskEnabled, isPhantomEnabled };
21 | }
22 |
23 | export function classNames(...args: any[]): string {
24 | var classes = [];
25 |
26 | for (var i = 0; i < arguments.length; i++) {
27 | var arg = arguments[i];
28 | if (!arg) continue;
29 |
30 | var argType = typeof arg;
31 |
32 | if (argType === "string" || argType === "number") {
33 | classes.push(arg);
34 | } else if (Array.isArray(arg)) {
35 | if (arg.length) {
36 | var inner = classNames.apply(null, arg);
37 | if (inner) {
38 | classes.push(inner);
39 | }
40 | }
41 | } else if (argType === "object") {
42 | if (arg.toString !== Object.prototype.toString) {
43 | classes.push(arg.toString());
44 | } else {
45 | for (var key in arg) {
46 | if (hasOwn.call(arg, key) && arg[key]) {
47 | classes.push(key);
48 | }
49 | }
50 | }
51 | }
52 | }
53 |
54 | return classes.join(" ");
55 | }
56 |
--------------------------------------------------------------------------------
/components/App.tsx:
--------------------------------------------------------------------------------
1 | import styles from "@components/App.module.scss";
2 |
3 | import Head from "next/head";
4 |
5 | import * as React from "react";
6 |
7 | // NOTE(jim): You'll need an SEO image, 1200px x 675px
8 | export default function App(props) {
9 | return (
10 | 6 | {props.children} 7 |
8 | ); 9 | } 10 | 11 | export default P; 12 | -------------------------------------------------------------------------------- /components/StatePreview.module.scss: -------------------------------------------------------------------------------- 1 | .preview { 2 | background: rgba(0, 0, 0, 1); 3 | color: rgba(255, 255, 255, 1); 4 | padding: 16px; 5 | border-radius: 4px; 6 | } 7 | 8 | .code { 9 | color: rgba(255, 255, 255, 0.7); 10 | font-size: 12px; 11 | line-height: 12px; 12 | font-family: lucida console, monospace; 13 | white-space: pre-wrap; 14 | overflow-wrap: break-word; 15 | } 16 | -------------------------------------------------------------------------------- /components/StatePreview.tsx: -------------------------------------------------------------------------------- 1 | import styles from "@components/StatePreview.module.scss"; 2 | 3 | import H2 from "@components/H2"; 4 | import P from "@components/P"; 5 | 6 | function StatePreview(props) { 7 | return ( 8 |11 | A JSON representation of the properties from the server, and the 12 | properties generated on the client. The benefit of this template is that 13 | no state management library is necessary. Feel free to add one if you 14 | like. 15 |
16 |{JSON.stringify(props.state, null, 2)}
17 | 58 | This method will delete string that holds the JWT in the 59 | cookie. To authenticate again you will need to sign in. 60 |
61 | 62 | 68 |75 | This method will delete the user entry from the user table. 76 | If the user is part of an organization this will delete the 77 | user from the organization but will not delete the 78 | organization row even if it has no members. 79 |
80 | 81 | 87 |97 | This is a traditional username and password sign in, if an 98 | account exists it will check if the credentials are correct, 99 | if the account does not exist a new user entry will be added 100 | in your Postgres database. You will need to figure out a way 101 | to verify the e-mail address on your own. 102 |
103 | 104 | handleChange(e, state, setState)} 110 | /> 111 | handleChange(e, state, setState)} 119 | /> 120 | 123 |137 | This is a traditional Google sign in flow. The necessary 138 | client ID and client secret are provided by Google. Unlike the 139 | local authentication strategy with a username and password, a 140 | user using this method will have a verified e-mail. 141 |
142 | 143 | {props.viewer && ( 144 |145 | If a user continues with a Google account that does not 146 | match the local authentication e-mail, it will sign that 147 | user into that account instead. 148 |
149 | )} 150 | 151 | 152 |161 | The user has Metamask installed in their browser. A user can 162 | now click the button below to connect their Ethereum address 163 | to {props.host}. This action will also create an Ethereum 164 | address entry in the Postgres table. 165 |
166 | 173 |184 | As the developer you could write some code that associates the 185 | Ethereum address with the authenticated user. However it is 186 | common advice to wait for an actual need. 187 |
188 |From this point on you can build your DAPP or DAO.
189 |198 | The user has Phantom installed in their browser. A user can 199 | now click the button below to connect their Solana address to{" "} 200 | {props.host}. This action will also create an Solana address 201 | entry in the Postgres table. 202 |
203 | 210 |221 | As the developer you could write some code that associates the 222 | Solana address with the authenticated user. However it is 223 | common advice to wait for an actual need. 224 |
225 |