This is a Next.js project bootstrapped with create-next-app
.
This app runs the front-end published sites for all tiny news organizations, using a single multi-tenant "platforms" project in Vercel, with data served through a GraphQL API from Hasura, along with a dynamic TinyCMS for organization-specific site configuration.
We based the structure of this applciation on the Vercel platforms starter kit. This means we build most of the site as part of the pages/_sites/[site]
folder. We then use middleware.js
to route incoming requests to the correct site. See the platforms starter kit linked above for more documentation on how this works.
Within this project we also build the API endpoints for interacting with Google Docs. You can find this at pages/api/sidebar
. The Google Apps Script project interacts with these API endpoints in order to preview, publish and unpublish documents.
Step 0
We use git-flow to make processes around feature development, staging deployment, stable production releases, and production hotfixes easier. You're likely on a Mac, in which case you can use Homebrew to set it up easily:
brew install git-flow
See the note at the end of this README for how to work with git-flow.
Step 1
Clone this project:
git clone git@github.com:news-catalyst/next-tinynewsdemo.git
And then initialize git-flow in your local checkout:
cd next-tinynewsdemo
git checkout stable
git flow init
You'll be prompted for a few settings - answer as noted here:
Branch name for production releases: stable
Branch name for "next release" development: main
Accept the default answers for all remaining questions by hitting <enter>
:
How to name your supporting branch prefixes?
Feature branches? [feature/]
Release branches? [release/]
Hotfix branches? [hotfix/]
Support branches? [support/]
Version tag prefix? []
And you're done!
Step 2
Change into the project directory:
cd next-tinynewsdemo
Step 3
Install dependencies:
npm install
Step 4
Set up an environment file for global settings:
We store our global environment settings in a separate private repo on GitHub. We use symbolic linking so that this repo remains up-to-date with that environment variable file.
First, clone the environment variables repo.
Switch to the next-tinynewsdemo repo. Then create a new linked file by running ln -s ../tnc-org-envs/.env.local .env.local
. This will create a new file in next-tinynewsdemo called .env.local
.
Any values that differ between the tiny news orgs are found in the settings
database table in Hasura. For development on your laptop, you'll want to make sure you're pointing at the staging database, which is called heroic-snapper, because that's the random name Hasura gave us for that stack and I missed the chance to rename it.
Step 5
Run the site in development mode: npm run dev
To build the site and serve from the static files:
npm run build && npm run start
If you want to debug server-side code, follow these instructions from Next.js.
Step 6
Open http://next-tinynewsdemo.localhost:3000 with your browser.
We switch between the different organizations' websites by changing the subdomain on localhost. "next-tinynewsdemo" is the testing "Oaklyn Observer" news organization subdomain.
The latest instructions on how to launch a new organisation are in a Google Doc and subject to change; please reference that for info.
NOTE: This code does not work since migrating to the Vercel Platforms structure.
Once you have the latest code, make sure you install dependencies for the WXR generator module - do this if you run into a babel-related error:
cd node_modules/wxr-generator
npm install
This might instruct you to install babel command line tools; I did this, then switched back to the top directory and was able to run the generator without a problem.
Then change back to the top-level directory. Make sure you have the site you'd like to export running locally. To generate for a different site, script/switch $orgSlug
to change your current .env.local
, then start up the site.
Finally, execute npm run wordpress
to generate the WXR file for each locale.
To test using Local WordPress:
npm run wordpress
)This project uses Jest to for unit testing. To run all unit tests, run npm run test
.
If you want to run all tests in a single file, use npm run test -- <File_Name>
.
If you'd like to run a single test, use npm run test -- <File_Name> -t <Your-Test-Name>
.
For more information, see the Jest documentation.
This project uses Cypress for integration and e2e testing. To run Cypress tests, follow these steps:
hosts: {
'*.localhost': '127.0.0.1',
},
npm run local:test
to start up the local front-end app. By default, it will use the Hasura GraphQL API for the staging Hasura environment. If you'd like to use a different environment, change the value of HASURA_API_URL for that command in package.json. Be sure to also change HASURA_ADMIN_SECRET in your .env.local file to match the environment you're using.dev:
. These are used for running Cypress tests within GitHub Actions. local:test
is intended for development on your local machine.npm run cypress:open
to open the cypress test runner window, which will then let you run one or all test files.Run the following where you have the Hasura repo checked out:
hasura migrate create init -from-server --admin-secret $PRODUCTION_ADMIN_SECRET
hasura migrate apply --endpoint $TESTING_HASURA_API_ENDPOINT --admin-secret $TESTING_ADMIN_SECRET --version $VERSION_GENERATED_FROM_ABOVE_COMMAND --database-name default
hasura metadata export --admin-secret $PRODUCTION_ADMIN_SECRET
hasura metadata apply --endpoint $TESTING_HASURA_API_ENDPOINT --admin-secret $TESTING_ADMIN_SECRET
You can get the value of \$PRODUCTION_ADMIN_SECRET by logging into hasura and copying the admin secret for the project.
If you have to repopulate the testing database with the basic data required for the webhook to work, run the following command from where you have this repo checked out:
yarn bootstrap:tests -n "Test Org" -s test-org -l en-US
To learn more about Next.js, take a look at the following resources:
You can check out the Next.js GitHub repository - your feedback and contributions are welcome!
To start working on a new feature, checkout the latest from main
and use git flow to create the new feature branch.
git checkout main
git pull origin main
git flow feature start feature_branch_name
Example: git flow feature start tinycms-auth
Make your code commits as usual. When the changes are ready for review and you want to open a PR:
git flow feature publish feature_branch_name
Then open a PR as usual on GitHub.
To start a release (for production) checkout the latest from main
and use git flow to create the new release branch:
git checkout main
git pull origin main
git flow release start 0.1.1
Then write up some quick release notes in CHANGELOG.md for the new version number and commit the changes.
To finish the release:
git flow release finish '0.1.1'
*** Note: We are not using hotfixes anymore. This section will be archived as we move off of GitFlow and onto a more modern trunk-based deployment model. Create a new release version for now.
If you have to fix something in production ASAP, and the main branch has changes that aren't ready to go live, you'll want to do a hotfix, checkout the latest from stable
and use git flow to create the new feature branch:
git checkout stable
git pull origin stable
git flow hotfix start hotfix_branch_name
Example: git flow hotfix start fix-this-nasty-bug
Code away, fix the bug, commit the changes, and then:
git flow hotfix finish hotfix_branch_name
You will then need to manually push your hotfix to the stable and main branches individually.
git checkout stable
git status // check that your hotfix changes are here
git push
git checkout main
git status // check that your hotfix changes are here
git push
For help, type: git flow
for a list of topics; git flow feature help
for example will provide info on subcommands available around feature branches. This page may also be useful for understanding GitFlow under the hood.