A client-side application that queries the GitHub API with a little bit of NASA imagery sprinkled on top.
- TypeScript - Language used for the project.
- React.js - JavaScript Framework.
- Next.js - React Framework.
- Ant Design - Design system / Components lib.
- Redux Toolkit - State & services/API management.
- Styled-Components - CSS-in-JS solution.
- GitHub API - Used to query repos, issues and stuff alike.
- NASA APOD API - Used to query images.
Make sure to have Git and Node.js 10.0.0 (or higher) installed.
-
Clone it or fork it.
-
Once you have your local copy, install its dependencies with a package manager (here we're going to be using npm):
npm install
Alternatevely you can use pnpm, the package manager used to create this project.
-
(OPTIONAL) Get yourself a NASA API key or use my own (available upon request @ gfmaximo97@gmail.com).
-
Create a
.env
file with the following properties:
NEXT_PUBLIC_GITHUB_SEARCH_ENDPOINT=* (E.g.: https://api.github.com/search/)
NEXT_PUBLIC_NASA_PLANETARY_ENDPOINT=* (E.g: https://api.nasa.gov/planetary/)
NEXT_PUBLIC_NASA_APOD_KEY=*
The planetary endpoint could very well be fixed. However, setting all endpoints on .env
is a project pattern I impose.
After having installed the dependencies and having configured .env
, you can then build the application with:
npm run build
Then after the build is done, start the application with:
npm run start
This will start the server at localhost:3000
This project uses Cypress to automate end-to-end tests.
All the test cases were written and configured on cypress/integration
.
Before testing, make sure that you have configured the cypress.json
file with the following parameters:
- port - Port where the application runs (default is 3000).
- githubSearchEndpoint - GitHub's search API (E.g.: https://api.github.com/search/).
- nasaPlanetaryEndpoint - NASA's API with access to the APOD microservice (E.g: https://api.nasa.gov/planetary/)
- (OPTIONAL) projectId - Id of the project for monitoring and integration with Cypress services, it's registered on my account (@ gfmaximo97@gmail.com), you can choose to leave it or delete it. Makes no difference.
{
"projectId": "p21ze9",
"env": {
"port": "3000",
"githubSearchEndpoint": "https://api.github.com/search/",
"nasaPlanetaryEndpoint": "https://api.nasa.gov/planetary/"
}
}
Also, make sure that the port you have set on cypress.json
matches the ports set on the package.json
scripts and that you have previously set the NEXT_PUBLIC_NASA_APOD_KEY
property on .env
.
After having configured everything, you can run the tests with:
npm run e2e
or if you want to run it solely on the console:
npm run e2e:headless
Performance metrics were measured with the help of DevTools Lighthouse & Vercel Analytics.
These are small samples collected with a very limited number of devices, the real performance scores may differ for better or for worse.
This project supports PWA:
Continuous Integration is done using GitHub Actions together with Cypress, you can check out the project's runs @ its Cypress Dashboard.
Continuous Delivery is done using Vercel for GitHub.
Project security oversight is done by Snyk. Good doggo, barks whenever there's a security issue and bites the hell out of vulnerabilities.
As of right now there is only one known vulnerability in the project caused by next-pwa, Snyk does not have a fix for it yet. So if you want to hack the project, I just gave you a clue...
- NASA's APOD API is somewhat slow and will sometimes throw 504 GATEWAY_TIMEOUT.
- NASA's APOD API video results that are hosted on 'https://apod.nasa.gov/' won't play because they set 'X-Frame-Options' to 'sameorigin'.
- Next.js will sometimes give a server-side warning about Ant Design trying to use useLayoutEffect under the hood.
- Offline fallback on PWA with next-pwa SUCKS. There are various issues on their repo about this and I couldn't get it to work properly myself. Maybe in the future I'll open an issue there. For now having an illustration on the
/search
page is enough for me.
- Pages must have .page.tsx exention.
- Do not create
./components
level components unless you plan to use them in more than one page or component. - Texts are stored in
texts
object variables with alphabet letters as key and text as value, it sucks but I haven't found anything better yet. Alternative pattern suggestions are welcome. - As mentioned previously above, all endpoints must be declared on the
.env
file. - Testing could be better, the project lacks unit testing and has extremely limited coverage of edge cases by the current integration/e2e testing done with Cypress.
- Commits must be done following Conventional Commits.
- If more than one person ever works in this project, ideally I would prefer that all GIT management be done following Trunk-based development.
- Cypress CI queries for a
package-lock.json
that matches the project'spackage.json
during the CI build phase. Meaning that, while you could use pnpm and yarn to manage dependencies, you'll always have to make sure that the project'spackage-lock.json
is up to date. It's a hassle to the point it made me abandon pnpm/yarn and just use npm instead. - There should be a skeleton of the layout during loading and page transitions. Or at least a loading spinner on all loading items.
- Brave Browser and other privacy-oriented browsers will block stuff from NASA's embedded videos, filling up the console with "blocked by client" errors.
- Chromium-based browsers with autofill enabled will warn about "Audit usage of navigator.userAgent, navigator.appVersion, and navigator.platform". I haven't found which package causes this.