diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0d993345..4ae5f039 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -89,10 +89,6 @@ The tests have a naming convention: In principle the `0-` tests don't have to worry about clobbering each other, whereas the `1-` ones do. -### Internationalization - -See [Internationalization.md](https://github.com/nolanlawson/pinafore/blob/master/docs/Internationalization.md). - ### Mastodon used for testing There are two parts to the Mastodon data used for testing: @@ -157,52 +153,19 @@ The Webpack Bundle Analyzer `report.html` and `stats.json` are available publicl This is also available locally after `yarn run build` at `.sapper/client/report.html`. -## Codebase overview +## Deploying -Pinafore uses [SvelteJS](https://svelte.technology) and [SapperJS](https://sapper.svelte.technology). Most of it is a fairly typical Svelte/Sapper project, but there -are some quirks, which are described below. This list of quirks is non-exhaustive. +This section only applies to `dev.pinafore.social` and `pinafore.social`, not if you're hosting your own version of +Pinafore. -### Prebuild process +The site uses [Vercel](https://vercel.com). The `master` branch publishes to `dev.pinafore.social` and the `production` +branch deploys to `pinafore.social`. -The `template.html` is itself templated. The "template template" has some inline scripts, CSS, and SVGs -injected into it during the build process. SCSS is used for global CSS and themed CSS, but inside of the -components themselves, it's just vanilla CSS because I couldn't figure out how to get Svelte to run a SCSS -preprocessor. +## Architecture -### Lots of small files +See [Architecture.md](https://github.com/nolanlawson/pinafore/blob/master/docs/Architecture.md). -Highly modular, highly functional, lots of single-function files. Tends to help with tree-shaking and -code-splitting, as well as avoiding circular dependencies. +## Internationalization -### emoji-picker-element is loaded as a third-party bundle +See [Internationalization.md](https://github.com/nolanlawson/pinafore/blob/master/docs/Internationalization.md). -`emoji-picker-element` uses Svelte 3, whereas we use Svelte 2. So it's just imported -as a bundled custom element, not as a Svelte component. - -### Some third-party code is bundled - -For various reasons, `a11y-dialog`, `autosize`, and `timeago` are forked and bundled into the source code. -This was either because something needed to be tweaked or fixed, or I was trimming unused code and didn't -see much value in contributing it back, because it was too Pinafore-specific. - -### Every Sapper page is "duplicated" - -To get a nice animation on the nav bar when you switch columns, every page is lazy-loaded as `LazyPage.html`. -This "lazy page" is merely delayed a few frames to let the animation run. Therefore there is a duplication -between `src/routes` and `src/routes/_pages`. The "lazy page" is in the former, and the actual page is in the -latter. One imports the other. - -### There are multiple stores - -Originally I conceived of separating out the virtual list into a separate npm package, so I gave it its -own Svelte store (`virtualListStore.js`). This never happened, but it still has its own store. This is useful -anyway, because each store has its state maintained in an LRU cache that allows us to keep the scroll position -in the virtual list e.g. when the user hits the back button. - -Also, the main `store.js` store is explicitly -loaded by every component that uses it. So there's no `store` inheritance; every component just declares -whatever store it uses. The main `store.js` is the primary one. - -### There is a global event bus - -It's in `eventBus.js`. This is useful for some stuff that is hard to do with standard Svelte or DOM events. diff --git a/bin/deploy.sh b/bin/deploy.sh deleted file mode 100755 index 339724c1..00000000 --- a/bin/deploy.sh +++ /dev/null @@ -1,41 +0,0 @@ -#!/usr/bin/env bash - -set -e -set -x - -PATH="$PATH:./node_modules/.bin" - -# need to build to update vercel.json -yarn run build - -# set up robots.txt -if [[ "$DEPLOY_TYPE" == "dev" ]]; then - printf 'User-agent: *\nDisallow: /' > static/robots.txt -else - rm -f static/robots.txt -fi - -# if in travis, use the $VERCEL_TOKEN -DEPLOY_COMMAND="vercel --scope nolanlawson" -if [[ ! -z "$VERCEL_TOKEN" ]]; then - DEPLOY_COMMAND="$DEPLOY_COMMAND --token $VERCEL_TOKEN" -fi - -# launch -URL=$($DEPLOY_COMMAND --confirm -e SAPPER_TIMESTAMP=$(date +%s%3N)) - -# fixes issues with now being unavailable immediately -sleep 60 - -# choose the right alias -DEPLOY_ALIAS="dev.pinafore.social" - -if [[ "$DEPLOY_TYPE" == "prod" ]]; then - DEPLOY_ALIAS="pinafore.social" -fi - -# alias -$DEPLOY_COMMAND alias "$URL" "$DEPLOY_ALIAS" - -# cleanup -$DEPLOY_COMMAND rm pinafore --safe --yes diff --git a/docs/Architecture.md b/docs/Architecture.md new file mode 100644 index 00000000..5fccb360 --- /dev/null +++ b/docs/Architecture.md @@ -0,0 +1,54 @@ +# Architecture + +This document describes some things about the codebase that are worth knowing if you're trying to contribute. +Basically think of it as a "lay of the land" as well as "weird unusual stuff that may surprise you." + +## Overview + +Pinafore uses [SvelteJS](https://svelte.technology) and [SapperJS](https://sapper.svelte.technology). Most of it is a fairly typical Svelte/Sapper project, but there +are some quirks, which are described below. This list of quirks is non-exhaustive. + +## Prebuild process + +The `template.html` is itself templated. The "template template" has some inline scripts, CSS, and SVGs +injected into it during the build process. SCSS is used for global CSS and themed CSS, but inside of the +components themselves, it's just vanilla CSS because I couldn't figure out how to get Svelte to run a SCSS +preprocessor. + +## Lots of small files + +Highly modular, highly functional, lots of single-function files. Tends to help with tree-shaking and +code-splitting, as well as avoiding circular dependencies. + +## emoji-picker-element is loaded as a third-party bundle + +`emoji-picker-element` uses Svelte 3, whereas we use Svelte 2. So it's just imported +as a bundled custom element, not as a Svelte component. + +## Some third-party code is bundled + +For various reasons, `a11y-dialog`, `autosize`, and `timeago` are forked and bundled into the source code. +This was either because something needed to be tweaked or fixed, or I was trimming unused code and didn't +see much value in contributing it back, because it was too Pinafore-specific. + +## Every Sapper page is "duplicated" + +To get a nice animation on the nav bar when you switch columns, every page is lazy-loaded as `LazyPage.html`. +This "lazy page" is merely delayed a few frames to let the animation run. Therefore there is a duplication +between `src/routes` and `src/routes/_pages`. The "lazy page" is in the former, and the actual page is in the +latter. One imports the other. + +## There are multiple stores + +Originally I conceived of separating out the virtual list into a separate npm package, so I gave it its +own Svelte store (`virtualListStore.js`). This never happened, but it still has its own store. This is useful +anyway, because each store has its state maintained in an LRU cache that allows us to keep the scroll position +in the virtual list e.g. when the user hits the back button. + +Also, the main `store.js` store is explicitly +loaded by every component that uses it. So there's no `store` inheritance; every component just declares +whatever store it uses. The main `store.js` is the primary one. + +## There is a global event bus + +It's in `eventBus.js`. This is useful for some stuff that is hard to do with standard Svelte or DOM events. diff --git a/package.json b/package.json index 8113c588..0d72302b 100644 --- a/package.json +++ b/package.json @@ -28,8 +28,6 @@ "test-unit": "NODE_ENV=test mocha -r esm -r bin/browser-shim.js tests/unit/", "wait-for-mastodon-to-start": "node -r esm bin/wait-for-mastodon-to-start.js", "wait-for-mastodon-data": "node -r esm bin/wait-for-mastodon-data.js", - "deploy-prod": "DEPLOY_TYPE=prod ./bin/deploy.sh", - "deploy-dev": "DEPLOY_TYPE=dev ./bin/deploy.sh", "backup-mastodon-data": "./bin/backup-mastodon-data.sh", "sapper-export": "cross-env PORT=22939 node -r esm ./node_modules/.bin/sapper export", "print-export-info": "node ./bin/print-export-info.js",