How To Create a React + Flask Project

One of the questions I get asked more often lately is how to create a project that combines a React frontend with a Flask backend. Instead of giving vague answers I decided to write a tutorial about it, including a video in which I go through the steps to create a simple but fully functional React+Flask project.


You need to install three packages on your machine:

  • Node.js: The JavaScript runtime that you will use to run your frontend project.
  • Yarn: A package and project manager for Node.js applications.
  • Python: A recent Python 3 interpreter to run the Flask backend on.

Please install these three packages using the instructions for your operating system before continuing with the tutorial.

Creating a Starter React Project

There are several ways to create a combined project with React and Flask. I prefer to start from the frontend because the project structure is much more complex than the backend. For this example I used the create-react-app generator to create a simple React project to start from:

$ npx create-react-app react-flask-app
$ cd react-flask-app

The npx command comes with Node.js. It is a simple project runner that downloads the requested command if it isn't already available and in the system's PATH. The first argument is the command to execute. The second argument is the name of the project to create. When this command completes, you will have a react-flask-app directory with a complete and fully functional simple react project.

Since you will work on this project from now on, you can cd into react-flask-app so that it is your current directory. If you list the directory you should see the top-level structure, which should be more or less like this:

$ ls -l
total 912
-rw-r--r--     1 mgrinberg  staff    2884 Feb 10 14:54 README.md
drwxr-xr-x  1027 mgrinberg  staff   32864 Feb 10 15:03 node_modules
-rw-r--r--     1 mgrinberg  staff     890 Feb 10 15:04 package.json
drwxr-xr-x     8 mgrinberg  staff     256 Feb 10 14:54 public
drwxr-xr-x    10 mgrinberg  staff     320 Feb 10 23:50 src
-rw-r--r--     1 mgrinberg  staff  454962 Feb 10 14:54 yarn.lock

Creating a Flask API Backend

The next step is to create the Flask project. Since I want to have both the frontend and backend combined into a single project, my preference here is to add one more top-level subdirectory where the Flask project will live:

$ mkdir api
$ cd api

I always create a virtual environment called venv in my project directory, so let's do that now:

$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ _

Note that the above is for Unix-based operating systems. If you are using Windows, then you will do this instead:

$ python -m venv venv
$ venv\Scripts\activate
(venv) $ _

For this simple example I need only two Python packages, the obvious Flask and also python-dotenv:

(venv) $ pip install flask python-dotenv

The Flask project can have any structure that you like, as long as its root is this new api subdirectory. In particular, you can use large and complex structures such as those in my Flask Mega-Tutorial or O'Reilly Flask book, as well as much simpler single file applications. In the spirit of keeping things simple, for this example I'm going to create a small, single file and single endpoint application. Here is my Flask API project, written as a single file called api.py:

import time
from flask import Flask

app = Flask(__name__)

def get_current_time():
    return {'time': time.time()}

This little API responds to the /time URL with a JSON payload such as this:

{"time": 1581527730.5866282}

If you are surprised that you are not seeing a call to the jsonify() function from Flask, you may not be aware that in recent releases of Flask your view function can return a dictionary, which gets automatically JSONified by Flask.

As you probably know, Flask imports the application from the place indicated by the FLASK_APP environment variable. To avoid having to manually set this variable every time, I'm going to write a .flaskenv file, which Flask automatically imports into the environment on startup if it finds the python-dotenv package installed. Here is my .flaskenv file:


Since I'm going to be setting up development environment, I also added the FLASK_ENV variable, with a setting of development, which enables Flask's debug mode.

At this point this basic Flask project is complete. To make sure that it is working well you can start it:

(venv) $ flask run
 * Serving Flask app "api.py" (lazy loading)
 * Environment: development
 * Debug mode: on
 * Running on (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 673-234-166

To stop the Flask server press Ctrl-C.

Now that the Flask part of this project is complete, let's leave the api subdirectory and go back to the root of the combined project.

(venv) $ cd ..

React Configuration Changes

The React project created by the create-react-app utility left a package.json file with the project's configuration. There are a couple of changes to make in this file to improve the integration between the React and the Flask sides.

The first change is to set up "proxy" redirection from React to Flask. You will see in a moment that the React project will run a web server on port 3000, while Flask runs its own server on port 5000. In most deployments, however, the frontend files and the API endpoints are all served from the same domain and port, which makes everything work seamlessly by avoiding cross-origin issues. The React project can be configured to redirect any requests it receives on its port 3000 that it does not understand into another server. This is configured simply by adding a proxy key at the bottom package.json:


  ... leave all other configuration options alone ...

  "proxy": "http://localhost:5000"

When you do this, do not forget to add a comma at the end of the previous line, as without that comma the file would not be a valid JSON file.

The other change I like to make is related to management commands. The React application uses yarn as a command manager. For example, the frontend server is started with the yarn start command. There is also a yarn test and a few more commands.

While this is entirely optional, the commands to manage the Flask app can be integrated with yarn as well. Somewhere in the middle of package.json you will find a scripts key. You can add any custom commands inside it:

  "scripts": {
    "start": "react-scripts start",
    "start-api": "cd api && venv/bin/flask run --no-debugger",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"

Here I've added one new entry called start-api, which I'm going to use to run the Flask server. The value of this key is the command that needs to be executed, which in this case involves changing into the api subdirectory and then running the flask run command.

Note that I have used the virtual environment path for the flask command so that I don't need to have the virtual environment activated. The nice thing about running the command in this way is that in the context of the Flask process all imports will work in the same way as with an activated virtual environment.

The --no-debugger option that I added in the command also deserves a mention. Since this Flask backend is strictly an API server, we will never be serving complete pages, so having the browser-based debugger enabled serves no purpose, as it's just going to mess up the JSON responses that the API returns. You will see stack traces of your errors in the terminal.

Adding the Flask Project to Git

The React starter project includes a git repository, which is actually a nice feature. To make it more friendly to Python there are a couple of things that need to be added to the .gitignore file:


This will prevent the virtual environment and the cache bytecode directories that Python 3 creates from ever getting added to source control. You can add any other things that you need here for your project as well.

Once your .gitignore is configured you can add all the new and modified files to git and commit the Flask backend:

$ git add .gitignore package.json api
$ git commit -m "flask backend"

Running the Combined Project

Okay, now the most exciting part. Let's run the application!

To do this you will need to use two terminal windows. One for the frontend server, and another for the backend. On the first terminal, start the frontend:

$ yarn start

This will take a few seconds and then a browser window will open with the example application from React loaded from http://localhost:3000:

React application screenshot

When you have the frontend running, switch to your second terminal and start the Flask backend at http://localhost:5000:

$ yarn start-api

Now both the frontend and backend are running. The frontend will redirect any requests it does not recognize to the backend. Both are watching their source code files and will restart when changes are made. I find this setup very convenient, because now I can just concentrate on writing code and the two servers refresh automatically as the code changes.

Invoking a Flask Endpoint from React

To complete this project, I'm going to expand the React application with a call to the /time endpoint that I defined in the Flask side. The main source file for the React application is src/App.js. This is this file after I put my changes:

import React, { useState, useEffect } from 'react';
import logo from './logo.svg';
import './App.css';

function App() {
  const [currentTime, setCurrentTime] = useState(0);

  useEffect(() => {
    fetch('/time').then(res => res.json()).then(data => {
  }, []);

  return (
    <div className="App">
      <header className="App-header">

        ... no changes in this part ...

        <p>The current time is {currentTime}.</p>

export default App;

As soon as you save the src/App.js file with the above changes, the application should update and show the current Unix time:

React application screenshot

There are a few small changes here. In the first line I added two new imports, useState and useEffect. I'm going to use the former to add the current time as state within the React application. The latter is used to create a callback that will be invoked when the application renders to the page, which is the time the Flask endpoint needs to be invoked.

In case you are used to writing React applications using classes and components, you should note that you can still do that, but the currently recommended practice is to use a function based approach. JavaScript projects tend to change often, sometimes in drastic ways. You should keep in mind that this isn't the only way to write a React application.

To add state to the application you use the useState() function:

const [currentTime, setCurrentTime] = useState(0);

The function returns two values, a getter and a setter for the new state. The getter is a simple variable, while the setter is a function. Using a setter function is necessary because by invoking the setter React is able to trigger updates in the parts of the application that depend on this state. The 0 that I'm passing as an argument to useState() is the initial value for this state variable.

Now that the state variable exists, it can be added to the template portion of the application:

<p>The current time is {currentTime}.</p>

This can be added anywhere in the template, and in fact, if you prefer you can erase the content used by the default React application and replace it with this.

The final part of this example application is to issue a request from the frontend to the backend:

  useEffect(() => {
    fetch('/time').then(res => res.json()).then(data => {
  }, []);

This needs to happen at a specific time when the React application is about to be displayed on the page. The useEffect() function is used to set up a callback function to be invoked when the application needs to prepare itself to render.

The first argument is the callback function. In this function I used fetch() to send the request over to the Flask API. Because of the proxy configuration I don't have to use the port 5000 URL, I can just use /time, which will make the request go to http://localhost:3000/time, before it gets redirected to port 5000. If you decide to not use the proxy feature and send the requests directly to port 5000, you will also need to configure CORS in the Flask server to allow this, since now you will be issuing the request across different origins.

The fetch() function returns a promise, so I set up a completion callback with the then() method. This callback receives the response as res, and then calls the res.json() method to convert the payload to a JavaScript object. This is yet another promise, so I have to chain a second then() with one more callback function. This final callback receives the JSON data from the request, which is an object with a single time attribute. Here I can use the setCurrentTime() setter function to update the currentTime state, which is referenced in the template, so as soon as the state changes the new value will be rendered.

The second argument to useEffect() is optional and can be set to the list of state variables on which this callback depends. In this case I wanted to display the time when the page appears initially and then stay fixed to that, so I'm sending an empty list to eliminate all dependencies. This means that this callback will be invoked on initial rendering and never again. If this argument isn't set, the default is to make this callback dependent on all state variables. This means that when the setCurrentTime() setter is called there will be another call into this function, which will cause the state to change again and keep causing recursive invocations in an endless loop.

Update: I have now written a second part to this tutorial where I show how to deploy this project to a production server.


So that's it, now you know how to create a project that combines React with Flask. As I hinted earlier, this isn't the only way to combine these two frameworks, so I encourage you to experiment with them and find what works best for you.

Do you use a different method? I'd love to know how you think it compares to mine, so let me know below in the comments!


  • #26 Miguel Grinberg said 2020-03-23T09:52:39Z

    @Jonathan: my guess is that you haven't properly set your FLASK_APP environment variable, there isn't really too many possibilities, Flask complains it cannot find the app which is configured via FLASK_APP, so it's got to be there.

  • #27 Sebastian Peralta said 2020-04-02T02:24:14Z


    You said "CORS(app)" is insecure but if we require an auth token to be sent in the header for each route then this should be a valid solution, correct?

  • #28 Miguel Grinberg said 2020-04-02T14:08:54Z

    @Sebastian: This isn't about correct vs incorrect, it is about levels of risk. If you allow anyone to contact your server, it is clear that the risk is greater, even if you have authentication. So you need to think about how much risk you are willing to accept in the name of convenience.

  • #29 yub said 2020-04-10T19:19:49Z

    Hi, I enconter an error in the console- Uncaught (in promise) SyntaxError: Unexpected token < in JSON at position 0. So the current time stuck on zero- "The current time is 0." There is an idea?

  • #30 Miguel Grinberg said 2020-04-11T09:33:36Z

    @yub: you appear to be returning HTML in the /time route, which is supposed to return JSON. Check the code of your Flask project against my version and look for mistakes.

  • #31 kmatjo said 2020-04-13T20:34:09Z

    Hi Miguel, Excellent tutorial that mixes both react and flask. When I follow it, the frontend console log has one error "Uncaught (in promise) SyntaxError: Unexpected token < in JSON at position 0". I guess this has something to do with the useEffect bit in app.js. Any ideas? Many thanks!

  • #32 Miguel Grinberg said 2020-04-13T22:56:48Z

    @kmatjo: That does not seem to be related to useEffect. That looks more like your /time route in the Flask app returning invalid JSON, possibly an HTML response, since the error talks about a < in the JSON payload. I have my version of the app on GitHub if you want to download it and compare it against yours: https://github.com/miguelgrinberg/react-flask-app.

  • #33 Daniel Reyna said 2020-04-14T20:50:25Z

    Hey great explanation. I am new to React, is there any way you can provide a tree structure so I can make sure my files are in the right directories for my project.

  • #34 Miguel Grinberg said 2020-04-15T23:10:45Z

    Daniel: I have a copy of this project on GitHub: https://github.com/miguelgrinberg/react-flask-app.

  • #35 Jeppe Johansen said 2020-04-16T08:38:49Z

    In this Front End, Back End setup would it then make sense to implement a WSGI server (e.g. uWSGI) for serving the flask API?

  • #36 Miguel Grinberg said 2020-04-17T13:46:39Z

    @Jeppe: For development I would not worry. On a production deployment, yes, it would make sense. Did you see the follow up article I wrote? I'm using Gunicorn to deploy the Flask API, but uWSGI would work the same.

  • #37 Dohd said 2020-04-21T17:01:44Z

    Using the setup described, I put up a timer feature on my React app that updates on each second but apparently, on simultaneous access of the app using more than a single browser-client terribly lags the server to the point of pc hanging. This happens since the timer triggers the DOM to be re-rendered and the fetch method is also called thus requests are forwarded to the Api-server continuously creating an unwarranted loop on the Api-server. I was hoping that if possible, you could modify your code so that only external request methods like fetch are dependent on the Api-server so that re-rendering of the DOM doesn't continuously fire requests to the Api-server.

  • #38 Miguel Grinberg said 2020-04-21T23:07:37Z

    @Dohd: the project as defined in this article/video prevents loops. This is specifically addressed by making the useEffect() handler have no dependencies.

  • #39 Aakarshan Dhakal said 2020-04-22T04:42:16Z

    Hey Miguel, Very helpful article and video. I really wanted to use flask-react combination for my project but I seem to have hit a roadblock. My question is: I was displaying a video stream using before. I have the following function that sends the stream as a response:

    @app.route('/video_feed') def video_feed(): return Response( VIDEO.show(), mimetype='multipart/x-mixed-replace; boundary=frame')

    I am unable to display this as a video stream on my react side. I tried console logging the Response on react side and it seems to be a Readablestream. Any ideas on how to approach this?

  • #40 Miguel Grinberg said 2020-04-22T10:17:57Z

    @Aakarshan: sorry but I don't understand. The video stream is going to end up in a <img> tag, since that is the only way the browser will play the stream. So what does that have to do with React?

  • #41 Aakarshan Dhakal said 2020-04-22T22:36:00Z

    @Miguel, yup you are totally right. I was overthinking. Realized soon after I posted. Thanks for your help. Look forward to your future tutorials and videos!

  • #42 Alain said 2020-04-24T14:39:47Z

    Hi Miguel!

    Thank you very much for all the great work you are doing in order to share your knowledge with the community. It is really impressive and I am really thankful.

    I am implementing a web application right now using Flask and... React! You'd have guessed. I am wondering how I can manage authentication and authorization?

    Right now, I am running Flask with flask_praetorian. But I am not sure this is a safe way to control access to the API. What would you recommend? Should I stick with JWT? I am afraid it is unsafe, but I can't figure out other solutions.

    Thank you anyway :) and keep the good work!

  • #43 Miguel Grinberg said 2020-04-24T22:56:07Z

    @Alain: JWTs are not safe or unsafe, it's how you use them what matters. I have not used Flask-Praetorian myself, but have heard good things about it.

  • #44 Naren said 2020-04-27T23:45:55Z

    using return res.json(); in the promise worked for the CORS error and the Unexpected token < in JSON at position 0 error

    useEffect(() => { fetch('/time').then(res => {return res.json();}).then(data => { setCurrentTime(data.time); }); }, []);
  • #45 John Mann said 2020-04-29T17:34:43Z

    I was playing with the tests on this project and if I have only 2 tests it works fine, but when I add a third test it fails, even if the test is identical. I'm not sure what is going on, I'm guessing the render object isn't being cleaned up, so I added afterEach(cleanup) and then if I have 5 tests (identical), tests 1,2,4 will pass and 3 and 5 will fail with a network request failed. Any suggestions/guidance?

  • #46 Miguel Grinberg said 2020-04-29T17:54:47Z

    @John: this is an extremely simple project, I did not add any tests. Are you writing front or back end tests? It is really impossible for me to comment on your tests without seeing them.

  • #47 Michael said 2020-05-02T04:32:01Z

    Is it good practice to separate front-end(react) from the backend(flask-api)?

    Combine both the frontend and backend into one director is convenient but couples frontend and backend together, right? Later if the project grows and maybe we have mobile frontend as well that is hitting the api. To scare only the api service but not the web frontend, current implementation does not work well.

    Would it be a good idea to have front end and backend to be separated projects to allow independent scaling of either frontend or backend?

  • #48 Miguel Grinberg said 2020-05-02T21:46:55Z

    @Michael: if you are the only developer and will be working on both front and back end, then I see it as convenient to combine both sides in one project. If you are working within a team, and there are some people working on the React side, and other people working on the Flask side, then maybe using separate repositories is better. There is no single answer to this, it really depends on your situation.

  • #49 Andy C said 2020-05-04T13:07:01Z

    I encountered the following error when start running react app. Not sure quite this is happening.

    Proxy error: Could not proxy request /time from localhost:3000 to http://localhost:5000. See https://nodejs.org/api/errors.html#errors_common_system_errors for more information (ECONNREFUSED).

  • #50 Miguel Grinberg said 2020-05-04T14:44:17Z

    @Andy: are you running the Flask app on port 5000?

Leave a Comment