Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[CHORE]: polished readme ready to make repository public #105

Merged
merged 4 commits into from
Jul 4, 2024
Merged

[CHORE]: polished readme ready to make repository public #105

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1966805
[FEATURE]: staging to production merge (#83)
slackermorris Jun 23, 2023
f423493
[FEATURE]: staging to production merge (#94)
slackermorris Jun 30, 2023
4423236
Merge branch 'develop'
slackermorris Jul 3, 2024
07d9b8e
chore: customised README
slackermorris Jul 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 22 additions & 113 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,26 @@
# Remix Grunge Stack
# 🧠 [Better Brain Blogging ](https://betterbrainblogging.com/)

![The Remix Grunge Stack](https://repository-images.githubusercontent.com/463325363/edae4f5b-1a13-47ea-b90c-c05badc2a700)
👆 That's a link.

Learn more about [Remix Stacks](https://remix.run/stacks).
👉 https://betterbrainblogging.com/ is another link.

```
npx create-remix --template remix-run/grunge-stack
```
Click on one to explore what Better Brain Blogging is all about.

## What's in the stack
<p align="center">
<a href="#the-why">🤔 The Big W "Why?"</a> •
<a href="#what-is-in-this-stack">💻 The Stack</a> •
<a href="#the-roadmap">🗺 The Roadmap</a>
</p>

Landing | Blogposts | Blogpost
:-------------------------:|:-------------------------:|:-------------------------:
![image](https://github.com/kwicherbelliaken/better-brain-blogging/assets/35620369/d1c24c80-d609-4639-b1f1-6c62eed89631) | ![image](https://github.com/kwicherbelliaken/better-brain-blogging/assets/35620369/b3bc1f3a-f2b3-4a85-9d6b-6d5498dc127e) | ![image](https://github.com/kwicherbelliaken/better-brain-blogging/assets/35620369/faa83c48-61b8-40a1-8039-211b51e92aba) |

## The Why

Everyone needs a blog. The universe is ravenous, craving for my opinion. Duh. Come on, man.

## What is in this stack?

- [AWS deployment](https://aws.com) with [Architect](https://arc.codes/)
- Production-ready [DynamoDB Database](https://aws.amazon.com/dynamodb/)
Expand All @@ -23,118 +35,15 @@ npx create-remix --template remix-run/grunge-stack
- Linting with [ESLint](https://eslint.org)
- Static Types with [TypeScript](https://typescriptlang.org)

Not a fan of bits of the stack? Fork it, change it, and use `npx create-remix --template your/repo`! Make it your own.

## Development

- Validate the app has been set up properly (optional):

```sh
npm run validate
```

- Start dev server:

```sh
npm run dev
```

This starts your app in development mode, rebuilding assets on file changes.

### Relevant code:

This is a pretty simple note-taking app, but it's a good example of how you can build a full stack app with Architect and Remix. The main functionality is creating users, logging in and out, and creating and deleting notes.

- creating users, and logging in and out [./app/models/user.server.ts](./app/models/user.server.ts)
- user sessions, and verifying them [./app/session.server.ts](./app/session.server.ts)
- creating, and deleting notes [./app/models/note.server.ts](./app/models/note.server.ts)

The database that comes with `arc sandbox` is an in memory database, so if you restart the server, you'll lose your data. The Staging and Production environments won't behave this way, instead they'll persist the data in DynamoDB between deployments and Lambda executions.

## Deployment

This Remix Stack comes with two GitHub Actions that handle automatically deploying your app to production and staging environments. By default, Arc will deploy to the `us-west-2` region, if you wish to deploy to a different region, you'll need to change your [`app.arc`](https://arc.codes/docs/en/reference/project-manifest/aws)

Prior to your first deployment, you'll need to do a few things:

- Create a new [GitHub repo](https://repo.new)

- [Sign up](https://portal.aws.amazon.com/billing/signup#/start) and login to your AWS account

- Add `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to [your GitHub repo's secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets). Go to your AWS [security credentials](https://console.aws.amazon.com/iam/home?region=us-west-2#/security_credentials) and click on the "Access keys" tab, and then click "Create New Access Key", then you can copy those and add them to your repo's secrets.

- Along with your AWS credentials, you'll also need to give your CloudFormation a `SESSION_SECRET` variable of its own for both staging and production environments, as well as an `ARC_APP_SECRET` for Arc itself.

```sh
npx arc env --add --env staging ARC_APP_SECRET $(openssl rand -hex 32)
npx arc env --add --env staging SESSION_SECRET $(openssl rand -hex 32)
npx arc env --add --env production ARC_APP_SECRET $(openssl rand -hex 32)
npx arc env --add --env production SESSION_SECRET $(openssl rand -hex 32)
```

If you don't have openssl installed, you can also use [1password](https://1password.com/password-generator) to generate a random secret, just replace `$(openssl rand -hex 32)` with the generated secret.
### Architecture

## Where do I find my CloudFormation?
I use Notion as my content management system (CMS). Each blog post is created as a page, and these pages are organized as entries in a database.

You can find the CloudFormation template that Architect generated for you in the sam.yaml file.

To find it on AWS, you can search for [CloudFormation](https://console.aws.amazon.com/cloudformation/home) (make sure you're looking at the correct region!) and find the name of your stack (the name is a PascalCased version of what you have in `app.arc`, so by default it's BlogCe66Staging and BlogCe66Production) that matches what's in `app.arc`, you can find all of your app's resources under the "Resources" tab.

## GitHub Actions

We use GitHub Actions for continuous integration and deployment. Anything that gets into the `main` branch will be deployed to production after running tests/build/etc. Anything in the `dev` branch will be deployed to staging.

## Testing

### Cypress

We use Cypress for our End-to-End tests in this project. You'll find those in the `cypress` directory. As you make changes, add to an existing file or create a new file in the `cypress/e2e` directory to test your changes.

We use [`@testing-library/cypress`](https://testing-library.com/cypress) for selecting elements on the page semantically.

To run these tests in development, run `npm run test:e2e:dev` which will start the dev server for the app as well as the Cypress client. Make sure the database is running in docker as described above.

We have a utility for testing authenticated features without having to go through the login flow:

```ts
cy.login();
// you are now logged in as a new user
```

We also have a utility to auto-delete the user at the end of your test. Just make sure to add this in each test file:

```ts
afterEach(() => {
cy.cleanupUser();
});
```

That way, we can keep your local db clean and keep your tests isolated from one another.

### Vitest

For lower level tests of utilities and individual components, we use `vitest`. We have DOM-specific assertion helpers via [`@testing-library/jest-dom`](https://testing-library.com/jest-dom).

### Type Checking

This project uses TypeScript. It's recommended to get TypeScript set up for your editor to get a really great in-editor experience with type checking and auto-complete. To run type checking across the whole project, run `npm run typecheck`.

### Linting

This project uses ESLint for linting. That is configured in `.eslintrc.js`.

### Formatting

We use [Prettier](https://prettier.io/) for auto-formatting in this project. It's recommended to install an editor plugin (like the [VSCode Prettier plugin](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)) to get auto-formatting on save. There's also a `npm run format` script you can run to format all files in the project.
All kudos for the landing page animation goes to Mike Bostock and his [Metaball Animation](https://observablehq.com/@mbostock/metaballs). I thought it looked coool so I stole it!

### Influences / References

- https://dev.to/martenstijs/how-we-used-notion-as-a-cms-for-our-blog-5b63: I used this to process the JSON Notion Page Block content as it seemed a good means of interpreting the Notion response payload.

- https://www.npmjs.com/package/notion-to-md: I was originally going to use this inside the $braindumpId loader and then process the returned Markdown into HTML using some interpreter. Fortunately, Notion chose against returning queried against resources as Markdown for JSON.

- https://web.dev/image-component/ optimised Image Component

- https://medium.com/front-end-weekly/progressive-image-loading-and-intersectionobserver-d0359b5d90cd: progressive image loading (helpful dissection of the possible approaches)

- https://jmperezperez.com/blog/medium-image-progressive-loading-placeholder/: more examples of progressive image loading
Loading