A fully-functioning template for building modern, maintainable websites.
- Modern design, with automatic dark mode
- Mobile-friendly
- Credentials and restricted pages
- Ability to send emails/texts
- Ability to upload images/files
- Search Engine Optimization (SEO) techniques
| Dependency | Purpose | Version |
|---|---|---|
| ReactJS | UI | ^17.0.2 |
| MaterialUI | UI Styling | ^5.0.0-beta.0 |
| Apollo | API (GraphQL) | ^2.25.0 |
| Prisma | Easier GraphQL building | ^2.30.2 |
| ExpressJs | Backend Server | ^4.17.1 |
| PostgreSQL | Database | postgres:13 |
| Redis | Task Queueing | redis |
Here is our guide for setting up all Vrooli repos. In addition to the common steps, you'll need to do the following:
Edit the file assets/public/business.json to match your business's data.
This project is set up so an admin can update various aspects without needing to mess with servers/code. To log in as an admin, use the admin credentials set in the .env file.
Once you are logged in, you should see a navigation option for "manage site". This includes links and descriptions to all of the admin functions. For inventory upload, there is an file that works with the example database, located in assets/private.
Open Graph is a metadata format that describes how your website should be shown when shared on social media. This data is set in the header, and can be edited at packages/ui/public/index.html. For more information, here is a guide from Facebook.
It is generally recommended to store data on an external server, but for smaller projects, local upload/download can also be useful. In this project, admins have a wide array of customization features, such as changing the images in a hero banner. Uploaded data is stored at <project_dir>/assets
Sometimes, generating TypeScript will give a "JavaScript heap out of memory" error. This is difficult to debug, so it is important that you try to catch these early. Sometimes this is caused by packages using different TypeScript versions.
If that doesn't solve this issue, you can debug TypeScript by changing yarn tsc to yarn tsc --generate trace-data. This will create a folder called trace-data, which contains a log that you can upload to about://tracing on Edge or Chrome. See TypeScript's performance tracing guide for more information.
When debugging the UI, we have a lot of options. There are console logs, Lighthouse testing, and React Developer Tools. The server, on the other hand, is a bit more complicated.
The server also supports console logs, but they aren't available during production. Instead, we can look at logs. These are generated at data/logs. You can also track logs from a remote server, which is described in the Remote debugging section of this document.
For performance measuring, we can use the 0x profiling tool to generate flame graphs. Getting this to work with Docker is a little cumbersome, but the result is worth it. You have to:
- Change
nodemonornode(depending on if you're calling the development or server script) to0x --node. Leave the arguments after the same. - Start the project as normal. You should see a file named
isolate-<random_characters>.log. This is not the flamegraph yet, but is used to generate it. - Perform whatever test you need so that
0xcan gather data. - To generate the flame graph, we have to stop the
0xprocess manually. Start by entering the server container:docker exec -it server sh - Enter
psand look for a process withnodeand0xin the name. Make note of the PID (the number on the left) - Enter
kill -SIGINT <0x_PID>. This will generate a folder called<0x_PID.0x. - Open the
.htmlfile in the generated folder to view the flame graph
It is often useful to send and receives emails with the website's address. Instructions to set that up can be found here
Picking the correct colors for your site can be easy or complicated, depending on how deeply you want to go into it (you could use color theory, for example). You also have to make sure that your theme's colors are different enough from each other to be distinguisable. I use this color tool to create a solid starting point. The site's theme is set in packages/ui/src/utils/theme.ts.
By default, this site automatically sets dark or light theme depending on your browser's settings. This is accomplished in packages/ui/src/App.ts.
GraphQL is a query language for APIs. It is a faster, understandable, and modernan alternative to REST APIs.
GraphQL syntax errors are notoriously hard to debug, as they often do not give a location. Luckily, this project is structured in a way that allows these issues to be tracked down.
In the schema directory, the GraphQL resolvers are split up into individual files, which are stitched together in the index file. In this file, the models object is used to combine all of the individual schemas. If you make this an empty array, you can comment out imports until the problem goes away. This allows you to pinpoint which schema file is causing the error. Common errors are empty parentheses (ex: users(): instead of users:) and empty brackets.
GraphQL is already typed, but it unfortunately doesn't play well with TypeScript's typing system. Instead of creating TypeScript types yourself (which is tedious), they can be generated automatically from an endpoint. This requires the backend server to be running.
See this video for more details.
- Start project locally in development mode (if ui is not runnable, that's fine. We just need a working server) -
docker-compose up -d cd packages/serveryarn graphql-generate
- Start project locally in development mode (if ui is not runnable, that's fine. We just need a working server) -
docker-compose up -d cd packages/uiyarn graphql-generate
Mobile devices can be simulated in Chrome Dev Tools, so testing is usually only done on your main development computer. However, if you'd still like to test on a different device, it will unfortunately not work out-the-box. This is because development uses the localhost alias. Your device will not be able to resolve this to the correct IP address (ex: 192.168.0.2), so you have to change it manually. There are 2 places where this must be done: (1) packages/server/src/index.ts; and (2) packages/shared/src/apiConsts.ts.
Brave Rewards is a service that allows users of the Brave browser to earn Basic Attention Tokens (BAT) for viewing ads. Enabling this on your website will also allow you to earn BAT. The ads appear as a small popup in the bottom right corner of the browser. To set this up:
- Sign up your website (and your socials if you'd like) here.
- On your website's server (see Deploying Project section to set this up), cd to
packages/ui/buildin your project's directory. vim .well-known/brave-rewards-verification.txt- Paste the text given in step 1 into the file, and save.
I hate ads as much as anyone else, but they're still an important monetization tool. The easiest way to set up ads is through Google AdSense. If you'd like to specify where the ads appear, you should follow these instructions to set up an "ad unit".
Some tips for implementing ads:
- Make sure the font matches your site's font (
Latoin this repo). - Make sure that pages and dialogs leave enough padding at the bottom so that nothing is cut off by a banner ad
- Make sure to change
data-ad-clientand related fields from this repo's ad components (if I've implemented them yet), so you receive the ad revenue instead of me.
Contributions are always welcome! If you have suggestions for improvements, please create an issue or a pull request💖
