cephalonscientia / wiki-reader Goto Github PK

See https://git-scm.com/book/en/v2/Git-Basics-Tagging on how to add version tags to commits. When the app reaches MVP, then all commits prior to that point should be labeled alpha-release.

Support internationalization of this app through i18next or other i18n libraries. Might need to do some tinkering because the library is in JS not TS. For localization, may integrate Phrase into the development stack.

Adopt Wikimedia's Design Guide (https://design.wikimedia.org/style-guide/) as a base for the site's light theme and Google's Material System (https://material.io/design/color/dark-theme.html) as a base for the site's dark theme.

This website may help with jumpstarting the creation of components: https://tailwind-elements.com/

Implement a theme switcher button that follows the user's scroll bar. Take advantage of TailwindCSS's dark variant when designing this feature (https://tailwindcss.com/docs/dark-mode).

• Should first respect the user's system preferences
• If user decides to switch theme, remember this setting for future browser sessions and every time user visits the site
  • May have to use cookies or Web Storage API
  • If users can be uniquely identified and want a consistent experience across multiple platforms, we may have to add an authentication system that stores user preferences in a database
• Transition between themes should not be instant, apply an ease timing function (non-linear) so user's eyes can adjust
• Button should not interfere with the readability of article content (add a sidebar or toolbar?)
• Button should be available regardless of where the user is on the page

Eventually, we would not solely depend on MediaWiki's Action API to fetch article content from wikis. There are three main reasons for doing so:

• So the app does not get blocked because of too many API requests
• Performance benefits for storing data on the edge
• To create a historical archive of article content

To achieve this, a database connection needs to be established to store cached versions of article content to be sent to the client. MongoDB is the preferred NoSQL database system to store document data like API calls that return a JSON response. For security reasons, the database connection string and other secrets should be stored in an environment file that will be ignored by Git.

Research whether or not app containerization is appropriate for this project. Some benefits of containerizations are:

• Project portability regardless of cloud platform or operating system
• Quicker CI/CD turnaround
• High scalability
• Decoupling application from host system for better security
  It may be done through Docker and Kubernetes.

It would be nice to have Storybook installed to document UI components and visually test components in isolation. See https://storybook.js.org/docs/vue/get-started/introduction for details.

Since this project is open source, there needs to be a basic code of conduct as a behavioral baseline for contributors to abide by in order to foster an inclusive and open environment. Will likely use https://github.com/simonv3/covenant-generator to generate the text.

Eventually, the web app will be hosted and deployed onto the cloud so there needs to be CI/CD process set up to build, test, and deploy the app. Likely would use GitHub Actions to facilitate CD but still debating on what cloud service to use (stuck between AWS and GCP). Unsure if containerization is appropriate for this project.

See https://v3.nuxtjs.org/docs/deployment/presets/ for deployment options. Nuxt.js projects can be deployed on serverless platforms, relying on edge computing to serve users. GitHub Pages may be a good start for app deployment as a static page https://nuxtjs.org/deployments/github-pages.

Web app should be able to choose which MediaWiki-based wiki to fetch article content from. We do not want to hard-code wiki endpoints within the business logic and views for flexibility. For now, on project build, the wiki chosen will be set in stone. If you want to change the wiki then you have to update the config and rebuild the app.

The following endpoints from the wiki's Special:Version page (e.g. https://en.wikipedia.org/wiki/Special:Version) must be stored as environment variables to enable this functionality:

• WIKI_ENDPOINT - Wiki endpoint (e.g. https://en.wikipedia.org)
• ARTICLE_PATH - Article path (e.g. /wiki/)
• ACTION_API - API path (e.g. /w/api.php)
• WIKI_NAME - Wiki name (e.g. English Wikipedia)
• WIKI_SKIN - Wiki skin path (e.g. /wiki/MediaWiki:Common.css)

Environment variables should be stored in a new .env file at the root project directory that should be added to .gitignore.

See the following on implementing environment variables:

• https://nuxtjs.org/docs/configuration-glossary/configuration-env/
• https://nuxtjs.org/tutorials/moving-from-nuxtjs-dotenv-to-runtime-config/
• https://nodejs.dev/learn/how-to-read-environment-variables-from-nodejs

Add ESLint and @nuxtjs/eslint-config-typescript as dependencies for linting TS code and add a new lint script to package.json lint: "eslint --config .eslintrc.json --ext .ts,.js,.vue --fix". See https://typescript.nuxtjs.org/guide/lint for more details.

Edit: Using vanilla JS until project migrates to Nuxt3. Instead, see https://medium.com/@gogl.alex/how-to-properly-set-up-eslint-with-prettier-for-vue-or-nuxt-in-vscode-e42532099a9c for a tutorial on how to set up ESLint.

Describe the solution you'd like
Write a shell script that builds project from src to lib folder, taking into account Tailwind CSS and transpiling TypeScript to JS. Running the command npm start should also build lib/stylesheets/output.css based on src/stylesheets/input.css.

Data compression can be used to reduce file sizes and bandwidth usage for data sent over networks. A great start would be to look into how brotli (https://github.com/google/brotli) can be integrated into the Webpack build flow. Webpack does have a community plugin (https://webpack.js.org/plugins/compression-webpack-plugin/) that supports brotli compression. Note that brotli is supported by all major browsers.

The main feature of this app is to fetch article content from MediaWiki-based wikis through MediaWiki's API. Clients should be able to search an article name (case insensitive) and have the article content be rendered on the webpage. There will be no server-side caching of these article contents for MVP release.

The end goal is to create a wiki reader boilerplate app that can be customized for branding needs.

Configure project to use TypeScript in place of JS for static typing and stricter programming discipline. See https://typescript.nuxtjs.org/guide/introduction

Includes all Vue components, tests, and nuxt.config.js.

Linter should also be configured to scan and lint .ts files.

Since Webpack does not compile nuxt.config.js, any environment runtime variables defined in the config will not be initialized and hence cannot be used by TS scripts at runtime.

TS2339: Property '$config' does not exist on type '{ components: { Header: {}; Navbar: {}; Article: {}; Footer: {}; }; mounted(): void; }'.

To solve this issue, TypeScript runtime wrapper needs to be installed (https://typescript.nuxtjs.org/guide/runtime/) to register ts-node before Webpack compiles any TS files to JS.

npm install @nuxt/typescript-runtime --save

Whenever the user submits a request with the name of an article (case insensitive), an API wrapper should be called to communicate with MediaWiki's Action API and return the article contents (if available) back to the user. If no article name matches what the user inputted, then just return a simple "No article found" message back to the user.

Eventually, we can extend this functionality to allow for web caching of article content to lower the number of direct API requests.

See https://socket.io/docs/v4/ and https://nuxt-socket-io.netlify.app/ for a possible tool that can help with developing this middleware.

Install TailwindCSS and add a new folder called styles to store CSS files. Issue is completed if TailwindCSS classes can be used in views. Blocked by issue #2 since Tailwind directives need to be resolved and compiled when app is being built.