Tsūka

Tsūka is an extremely simple React app for converting currencies. It was built from scratch using only React and PropTypes. No complex state management, static type checking, and UI library needed!

Tsūka allows you to convert currencies with ease. It uses data from Fixer, the touchstone foreign exchange (Forex) rates compiled from leading market data contributors.

Tsūka or 通貨 literally means “Currency” in Japanese and 通貨換算ツール (tsūka kansan tsūru) means “Currency Convertion Tool” or “Currency Converter”.

Table of Contents

Getting Started

• Live Demo
• Configuring the Development Environment

Specifications

• Features
• Technology Stack
• Development Workflow
• Third-party Services
• Browser Support
• Related Projects

Appendix

• Development Milestones
• Changelog
• Acknowledgements
• Credits
• Licenses

Live Demo

Tsūka is running on Heroku at https://tsuuka.herokuapp.com and Storybook (component library for Tsūka) is hosted on Netlify at https://tsuuka.netlify.com.

App sleeping... as Tsūka and its API run on Heroku’s free plan, when an app on Heroku has only one web dyno and that dyno doesn’t receive any traffic in 1 hour, the dyno goes to sleep. When someone accesses the app, the dyno manager will automatically wake up the web dyno to run the web process type. This causes a short delay for this first request, but subsequent requests will perform normally. For more information, see App Sleeping on Heroku.

Monthly limit as Tsūka API gets current and historical foreign exchange (Forex) rates from Fixer’s free plan, therefore Tsūka API is restricted to making 1,000 API calls per month. For more information, see Fixer Plans.

Back to top

Configuring the Development Environment

Prerequisites

Before getting started, you are required to have or install the following tools on your machine:

• Git (v2.17.2*)
• GNU Bash (v3.2.57*)
• nvm (v0.33.5*) and Node.js (v10.15.1*)
• npm (v6.4.1*) or Yarn (v1.3.2*)

Note: if you are using Mac running macOS (v10.12 Sierra*), you are set with Git and GNU Bash.

Optional, but nice to have:

• Visual Studio Code**
• Google Chrome**

While it is not a requirement, I recommend using Visual Studio Code as your editor so you can take advantage of all the awesome features Visual Studio Code extensions enable.

Setup

1. Clone Tsūka from GitHub repository and change the current working directory:

git clone https://github.com/rxseven/tsuuka.git
cd tsuuka

2. Open the project with your editor of choice or with Visual Studio Code.

3. Switch to a specified Node version:

nvm use

Starting the development server

1. Run the development server by running the following command:

yarn start

2. Open http://localhost:3000 to launch the app in the browser.

Tip: press control + c to stop the development server.

Running Storybook

1. Run a UI development environment and playground for UI components with Storybook by running the following command:

yarn storybook

2. Open http://localhost:6006 to launch Storybook in the browser.

Tip: press control + c to stop the server.

Running tests

Run one of the following commands to run tests with Jest and Enzyme:

yarn test
yarn test:coverage
yarn test:debug
yarn test:silent
yarn test:staged
yarn test:verbose

Note: by default, when you run test in watch mode, Jest will only run the tests related to files changed (modified) since the last commit. This is an optimization designed to make your tests run fast regardless of how many tests in the project you have. However, you can also press a in the watch mode to force Jest to run all tests.

Note: code coverage reports will be generated in the local ./coverage directory. This directory is listed in .gitignore file to ensure that it will not be tracked by the source control.

Tip: press control + c to stop the running tests.

Running JavaScript linting

Run the following command to run JavaScript linting with ESLint:

yarn lint:script

Running stylesheet linting

Run the following command to run stylesheet (SCSS) linting with Stylelint:

yarn lint:styles

Running Styled Components linting

Run the following command to run Styled Components linting with Stylelint:

yarn lint:styled

Formatting code

Run the following command to format your code against Prettier and ESLint rules:

yarn format

Creating an optimized production build

Run the command below to build the app for production. It correctly bundles the app in production mode and optimizes the build for the best performance. The build will be minified and the filenames include the hashes.

yarn build

Note: the production build will be created in the local ./build directory. This directory is listed in .gitignore file to ensure that it will not be tracked by the source control.

Exporting Storybook as a static app

Storybook comes with a tool to export your Storybook into a static web app. Then you can deploy it to any static hosting service. To do so, run the command below to build the static app:

yarn build:storybook

Note: the production build will be created in the local ./storybook-static directory. This directory is listed in .gitignore file to ensure that it will not be tracked by the source control.

Analyzing the bundle size

To analyze and debug JavaScript and Sass code bloat through source maps, run the following commands respectively to create an optimized production build and start analyzing and debugging the bundle size with Source Map Explorer:

yarn build
yarn analyze:bundle:sourcemap

Once the analyzing process has finished and the report was generated, you will automatically be redirected to the browser displaying the treemap visualization of how the space is used in your minified bundle.

Running the production build locally

1. Change base API URL in .env.production as fllows:

# API URLs
REACT_APP_API_URL=http://localhost:5000/api/v1

Why do we need to change the base URL? Because all build commands will load environment variables from .env.production despite the fact that we run this command locally. However, the production Tsūka API only allows incoming requests from two domains (see the configuration here), which are https://tsuuka.herokuapp.com and https://tsuuka.netlify.com, other origins will be blocked by CORS.

2. Run the following commands respectively to create an optimized production build and start an HTTP server serving the static app locally:

yarn build
yarn start:static

3. Open http://localhost:8080 to launch the production app in the browser.

Tip: press control + c to stop the server.

Back to top

Running static Storybook app locally

1. Change base API URL in .env.production as fllows:

# API URLs
REACT_APP_API_URL=http://localhost:5000/api/v1

2. Run the following commands respectively to create a static Storybook app and start an HTTP server serving the static app locally:

yarn build:storybook
yarn storybook:static

3. Open http://localhost:8081 to launch the static Storybook app in the browser.

Tip: press control + c to stop the server.

Back to top

Features

Convert currencies using daily Fixer's Forex rates.

Back to top

Technology Stack

Tsūka was built with React and Node.js, one of the most popular stack of technologies for building a modern single-page app.

Web application

• React, React Router, React Transition Group, React Helmet
• Recompose, Lodash, Ramda, Axios, Yup, PropTypes
• Styled Components, Sass, PostCSS, CSS modules, Bootstrap
• More...

REST API

• Node, Express, TypeScript
• CORS, Body-parser, .ENV, Lodash

Note: REST API for Tsūka can be found in this repository.

Back to top

Development Workflow

• Project bootstraping with Create React App
• JavaScript and assets bundling with Webpack
• Development server and live reloading with Webpack DevServer
• JavaScript transpiling with Babel
• CSS-in-JS with Styled Components
• CSS pre-processing and transforming with Sass, PostCSS, and CSS modules
• JavaScript linting with ESLint
• Stylesheet and Styled Components linting with Stylelint
• Code formatting with Prettier
• Automate testing with Jest and React Testing Library
• Assets analyzing & debuging with Source Map Explorer & Webpack Bundle Analyzer
• Type checking with PropTypes
• Code debugging with Visual Studio Code and Chrome Debugger
• Pre-commit hooking with Husky and Lint-staged
• CI/CD with GitHub, Travis CI, Coveralls, Heroku, and Netlify
• Developing UI components in isolation with Storybook

Note: the complete guidelines are available in this project.

Back to top

Third-party Services

Infrastructure

• Heroku - cloud platform as a service
• Netlify - hosting & serverless backend services for static websites

Cloud computing and Platforms

• Fixer - API for current and historical foreign exchange (Forex) rates
• REST Countries - API for getting information about countries
• Country Flags - API for loading any country flag

Software as a Service

• GitHub - web-based hosting service for version control using Git
• Travis CI - continuous integration
• Coveralls - test coverage history and statistics

Back to top

Browser Support

Because this project uses CSS3 features, it’s only meant for modern browsers. Some browsers currently fail to apply some of the styles correctly.

Chrome and Firefox have full support, but Safari and IE have strange behaviors.

Back to top

Related Projects

Tsūka API

REST API for Tsūka built with Node, Express, and TypeScript.

Setup React App

React & Redux starter kit with best practices bootstrapped with Create React App.

Back to top

Development Milestones

• Implement animations
• Optimize the app’s performance
• Add more unit, integration, and E2E tests to cover the entire app
• Upgrade Storybook to v5
• Upgrade React Router to v5
• More...

Back to top

Changelog

See releases.

Acknowledgements

Tsūka is an open-source project built and maintained by Theerawat Pongsupawat, frontend developer from Chiang Mai, Thailand.

Credits

This project was bootstrapped with Gyararī.

Licenses

The content of this project itself is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International license, and the underlying source code is licensed under the GNU AGPLv3 license.

---

* the minimum required version or higher | ** the latest version