Tutorial: Create a real-time web game with Django Channels and React

Jan 20, 2017

The Game!

To start, we need a new set of components that will work as our Game. Create a new folder under templates/components named game. Inside that folder, create index.jsx, GameBoard.jsx and game.html files.

Add the following to each of those files:

Just as with the Lobby components, we need an index.jsx file that Webpack will use as an entry point. Here are the key points in that file:

  1. Imports “GameBoard.jsx” component (yet to be created)
  2. Creates a “game socket” (game_sock) to handle Channels communication unique to the game instance
  3. Gets the current user and Renders the GameBoard base component once a user is found
Our game.html file is really just a placeholder for the GameBoard component. It also has some standard Django/html to present the two players.
This won’t work, however, until we let Webpack know it needs to bundle it up for us. So, modify your webpack.config.js, adding a new entry:
With that, we can restart Webpack, but we’ll see that it failes to bundle our new components. This is due to a bad reference to a missing GameSquare component.

GameBoard and GameSquare

Obstruction is a game of claiming squares. The game board can be an even number of squares like 6×6 square or a rectangle with dimensions like 10×11.

Our Game model already creates a 6×6 board when a game object is created. This is defined by the cols and rows fields in the model. If you take a look at the create_new model method, you see that we just loop through the rows and create X number of columns for each row as defined by those fields. For each of these, we create a GameSquare object that will keep track of its owner and status throughout the game.

So, we know that each game already has a board ready to display. A board is essentially a collection of squares. We already have a board component, so let’s create a square component. In a new GameSquare.jsx file under the templates/components/game/ folder, add this code:

A brief breakdown of that component:

  • Lines 3-7: Icon images loaded as variables so React can reference them as needed
  • Lines 10-17: The constructor that sets the owner of the square and the type of possession – either a direct select or surrounding square.  More on that later.
  • getStatus() determines which icon to use to indicate the status
  • checkAvailable() is a function that determines if it’s a valid square on which to move.
  • takeOwnership() informs the server of a move through Channels.
  • squareClicked() is a click handler which calls the two previous methods to claim a square.
  • render() is the React lifecycle method that will finally render the square.


After creating that file if you run Webpack again ( ./node_modules/.bin/webpack --config webpack.config.js --watch ), it should pack the Game components into a separate bundle from our Lobby components. This allows us to reference only that specific bundle in the Django template using the webpack_loader (line 4 in game.html).

If you run the Django server now and visit the Game page, you’ll see that it lists both players and where the game board will be, it just says “Loading…”. This is a placeholder for the game board if it’s not loaded or if the board doesn’t exist. If we take a look at the browser javascript console, you’ll see there is a 404 error with the client attempting to call the /game-from-id/ endpoint. So, it’s attempting to get the game, but never can.

You may be wondering how, if we don’t have the game object, we’re able to show the players and the game name. This is because those parts are rendered in the standard Django template in game.html. 

This goes back to what we talked about earlier. Using Django, Channelsand the Rest Framework, we have options on how to deliver the data to the client. I wanted to show each of the different ways in this tutorial, but in real practice, you would have a much more consistent way of using these features. Another good option would be to serialize the game into JSON and the deliver it in the normal Django context from the view. It just needs to be JSON so React can easily work with it.

Anyway, let’s wire up the endpoint now. Update your urls.py to look like this (new lines highlighted):

What we’ve added there is the /game-from-id/ endpoint and two additional URLs endpoint for /game-squares/ which we’ll also need.

Now, we need the ViewSets for those, so add the following to your api_views.py file:

And those ViewSets are looking to use some DRF serializers, so we need to add those too. Add these two classes to the bottom of your serializers.py file:


So we have the DRF code in place, but we’re also using Channels in this new component, so we need supporting Consumer code for that. Add the following to the bottom of your Consumers.py file:

Now with Webpack and a runserver, you can visit your game page again you should now have a nice, little, ugly 6×6 grid of squares. Each square will just be gray to start because no players have claimed it.

In our game, when the game object is created, the “creator” of the game is the first player to make a move. You can see the current player just above the board and this is the only player that can make a move. However, you’ll notice that when you click a square, nothing happens. A clicked square needs to make a call through the websocket, and the websocket needs an socket url to send the message. We’ve added the necessary lines to the Consumer to receive the message, so now let’s add the route to routing.py. Add the highlighted line:

Great! Now refresh both browser windows and let’s see this in action! If you click a gray square as a “Current Player”, you should see it claim immediately on that window, as well as on the other player’s browser! It’s a functional game at this point!

Now, you may be wondering how the client is getting the latest updates. We didn’t add any code to serialize the data and send it down to the client this time. Well, when we did this before, we added code in the signals.py to listen for changes in the Game model. We could do that again, but as I mentioned before, there are several ways we can send an update through Channels. I wanted to show yet another way to do this in this tutorial, so you’ll find a method named send_game_update in the Game model code.

The only thing Channels needs to send the message to a group, is the group name. Our game’s group name is “group-{id of game}”. So this is easy as we know the game ID in the model. Also, by adding it to a model method, we can call it only when we want to update the client. A signal receiver is called every time a model is saved. So doing it this way, may work better for you in your projects. But there is not necessarily a “best way” that covers every situation.

Play the game out…

Go ahead and take turns claiming squares for each player until there are no more squares to claim. When the last one is taken, “Current Turn” changes to “The Winner”, listing the last player who took a turn.

So, it’s a functional game at this point, but there are MANY things we can add to spice it up and polish it off. Let’s do one thing now.

To show how we can further extend the game experience, I thought would be nice to show a log of game actions and to give a place for the two players to chat back-and-forth. Django Channels gives us an easy way to tie live updating functionality!  And if you take a look at the models.py file, you’ll see we’ve already had some Log code in place. How convenient!

Continue on, we’re almost done….

1 2 3 4 5 6 7 8 9

  • hello,
    when I run your code, but the web don’t show the game, what’s happend?

    Gia Cat 09/27/2018 12:34 pm Reply
    • Are you going through the tutorial? Or are you running the example project from github?

      codyparker 09/28/2018 8:46 am Reply
  • Do you have a similar project but with channels 2.0? Do you plan to update this one?

    marsel 08/30/2018 9:53 am Reply
    • Yes, I’m actually working on one now. Hopefully I’ll have it ready in October, but my free time is tight right now.

      codyparker 09/28/2018 8:47 am Reply
  • I am getting an error, “ImportError: cannot import name ‘Group'”, while trying to import Group from channels in models.py. I am using channels 2.0.2. Please help.

    don 03/28/2018 8:31 am Reply
    • Yeah, this tutorial is based on a very early version of channels – 0.17, I believe. Version 2.0.2 has quite of few changes from that old version, including requiring Python3. Here is an issue on the official github that deals with the error you’re seeing: https://github.com/django/channels/issues/989

      I will try to get the tutorial updated to Django 2.0, Python 3, and the latest channels version soon.

      codyparker 04/23/2018 9:15 pm Reply
  • Hey,

    I’m trying to follow your tutorial, but I keep running into the following error:

    OSError at /lobby/
    Error reading [PATH]\webpack-stats.json. Are you sure webpack has generated the file and the path is correct?

    Any idea how to fix it?

    Graeme 03/14/2018 10:32 am Reply
    • Sorry, I didn’t reply sooner. If the file is being generated, check your STATS_FILE setting under WEBPACK_LOADER in settings.py. It’s possible that it isn’t pointing to the correct location for the file.

      If the file isn’t being generated, webpack may not be running properly. Are you seeing errors when you run wepback?

      codyparker 04/23/2018 9:24 pm Reply
  • That is very good, I was making similar stuff as a video on my language and this sharing is very useful.
    Power of sharing, thanks again.

    ozan 10/29/2017 3:48 pm Reply
  • When will the index.jsx be called ?

    Orang 10/08/2017 6:30 pm Reply
    • The index.jsx files are bundled with webpack (set on lines 8 and 9 in webpack.config.js). Those are the bundles that are loaded with the Django Webpack Loader and rendered on the related html pages (lobby.html and game.html).

      codyparker 10/09/2017 10:07 am Reply
  • I got a few questions to make the game a little bit more complex

    Is it possible to allow to the user give a name for the room?
    Is it possible to allow more than 2 players? (obviously adding the correct img stuff)
    If the answer from above is yes, can the user choose a “limit” for ppl to connect before starting the game?


    Leonardo 10/06/2017 7:19 pm Reply
    • Yes, each of those suggestions would work just fine:

      1.  Name of the room: Adding a “name” CharField to the Game model (models.py) would hold the value and then you would just need to add a bit to the create_new model method to set it. You would also need to allow the game creator to provide that name when creating it, instead of just clicking a button. But that name value would then just be passed along in the JSON to Channels in the sendSocketMessage call in the onCreateGameClick() method of PlayerGames.jsx.
      2. This could be added with a bit more work, but essentially you would want to change the Game model to have a ManyToMany relationship to Users. Aside from that, several other parts of the code and GUI would need to be updated because it’s pretty hardcoded to two players at the moment. But if there were multiple users in a game, Channels would work the same – everyone would get game updates without a problem.
      3. And yes, once the game was converted to use multiple players in a game, you could just have the game creator specify the max limit and then store that as a max_players IntegerField in the Game model….and then allow users to join up to that limit.


      codyparker 10/09/2017 10:20 am Reply
  • Thanks for this django/react tutorial. It is awesome helping me get my head around React and putting all the pieces together!!

    johnedstone 08/12/2017 8:05 am Reply
    • Great to hear! I’m glad you found it useful. Thanks for letting me know.

      codyparker 08/12/2017 4:21 pm Reply
  • Thank you so much for writing this tutorial!
    From your description, it seems like moves and player messages should update automatically, however when I run it, they only update after a manual refresh of the page. Am I misunderstanding how the website works?

    Missa 07/26/2017 12:58 pm Reply
    • The log should update when new chat messages are created or moves are made. I would check to make sure the game.send_game_update() method is being called at the appropriate times. Also, check the browser console for any errors on the client-side. That may give you more of a clue to the issue as well.

      codyparker 07/26/2017 1:48 pm Reply
  • Thanks for writing this tutorial! However, some things that may be confusing to a beginner: startapp game is going to create a game/views.py by default, and anyone that forgets to move views.py is going to have a package conflict. Also, from views import * inside __init__.py should be from .views import * just to avoid any namespace mismatches. I recommend you keep the default views.py.

    Daniel 06/11/2017 2:41 pm Reply
    • Thanks for your comments, Daniel. Yes, I thought that splitting the views could be confusing, but it’s something I like to do to organize views of different types. So here, I didn’t want to combine the DRF API views with the “standard” Django views. Also, the tutorial wasn’t exactly intended for beginners, but maybe I can clarify the views split a little more in the post. Also, thanks for catching the import fix. I had already updated the imports in the git project, but missed it in the post.

      codyparker 06/13/2017 10:11 am Reply
  • Hello! Great tutorial! I have a question, I want to use foundation-sites in my project. I am following you tutorial and instead of using bootstrap precompiled css I would like to install foundation with bower maybe? I know how to use the “foundation new” command to create a new project but I would like not to create a new project but integrate foundation sites with mine!

    David Anchorena 06/05/2017 8:45 am Reply
    • Hey David, sorry I haven’t worked with Foundation yet. But it looks like you can just use the CSS itself and avoid the CLI site generation: http://foundation.zurb.com/sites/download/

      You could just include this as you would any other CSS, and my guess is that if you install the full Foundation package with NPM, you could just reference the CSS there as well.

      codyparker 06/06/2017 2:38 pm Reply
  • not sure if it’s a django versioning thing or what, but on page 1 of this tutorial you are no longer allowed to specify views with strings and they must be callable, suggested edit follows:


    from django.conf.urls import url
    from django.contrib import admin
    from game.views import *

    urlpatterns = [
    url(r’^admin/’, admin.site.urls),
    url(r’^register/’, CreateUserView.as_view()),
    url(r’^login/$’, ‘django.contrib.auth.views.login’, {‘template_name’: ‘login.html’}),
    url(r’^logout/$’, ‘django.contrib.auth.views.logout’, {‘next_page’: ‘/’}),

    url(r’^$’, HomeView.as_view())


    from django.conf.urls import url
    from django.contrib import admin
    from django.contrib.auth.views import login, logout
    from game.views import *

    urlpatterns = [
    url(r’^admin/’, admin.site.urls),
    url(r’^register/’, CreateUserView.as_view()),
    url(r’^login/$’, login, {‘template_name’: ‘login.html’}),
    url(r’^logout/$’, logout, {‘next_page’: ‘/’}),

    url(r’^$’, HomeView.as_view())

    will 05/23/2017 9:21 am Reply
    • Yep – you’re right, thanks for letting me know! I’ve updated the urls.py code.

      codyparker 05/23/2017 12:30 pm Reply
  • Thank you so much, one of the most complete tutorials I have seen. Not all persons are willing to teach this things together, and the complexity of the scenario gives us good bases. This types of tutorials (even paid) are hard to find. Again, thank you.

    Pepe 05/07/2017 9:14 pm Reply
    • Thank you for the nice comments! I’m glad you found the tutorial helpful.

      codyparker 05/08/2017 8:35 am Reply
  • Can you please show one example on how I can make api post call from react to django drf?

    Is there any reason why all “post” calls are done via sockets not api in this tutorial?

    Said 02/07/2017 3:47 am Reply
    • You can see a few examples of calls from React to the DRF backend in my post. For example, take a look at the getGame() method on the GameBoard.jsx component. That method calls the DRF SingleGameViewSet endpoint to get game details.

      And as I mentioned in the post, I tried to mix up different ways of getting data from the Django backend to the React frontend. I wanted to show different ways of achieving the same thing: sending data through the standard Django response via context, DRF calls to the backend, and Django Channels websocket calls. In reality, this isn’t how I would structure a production app, but I was hoping it would be informative. Hopefully not confusing at the same time.

      codyparker 02/07/2017 2:40 pm Reply
  • Wow! Thanks again for sharing this tutorial. I am amazed by your generosity. The tutorial is intense.

    Let me give some suggesting for how you can improve it. I found that very often the flow of tutorial is going from big concepts (code snippets) to a smaller ones. For example several times you are first putting together some views, react components or api_views and then go to show some serializers, consumers, routers, urls and so on. This can be sometimes confusing, since a student can receive error messages that those small parts are not yet existed. I think going from small concepts to bigger would be more easily to understand. Also, please check your github code. I think it does not work if you just download it and want to use. Several imports are configured improperly (signal in apps.py, for instance)

    Thank you again!

    Said 02/07/2017 3:44 am Reply
    • Thanks for suggestions. Yes this was my first large tutorial so it definitely could be optimized and improved. I did the GitHub project well before the post, but it worked for me when I last tried it. It could be a python2/python3 import issue. I’ll update that tonight and get it working.

      codyparker 02/07/2017 1:16 pm Reply
  • not sure if the instruction on page 8 is correct

    class ClaimSquareView(APIView):

    def get_object(self, pk):
    return Game.objects.get(pk=pk)
    except Game.DoesNotExist:
    raise Http404

    def put(self, request, pk):
    game = self.get_object(pk)
    # update the owner
    return Response(serializer.errors)

    – no import for Http404
    – serializer is not defined

    Said 02/07/2017 1:36 am Reply
    • You’re right! That view isn’t even needed… I think I started going that direction to claim a square, but moved it to a Channels call using the consumer instead. I’ve removed that reference and the url reference.

      Thank you very much for your suggestions and bug reports! I’ve added you to the “Thank you” section at the bottom of the post.

      codyparker 02/07/2017 3:50 pm Reply
  • on page 7 views.py also should import

    from django.contrib import messages

    Said 02/07/2017 12:31 am Reply
    • Added it, thank you.

      codyparker 02/07/2017 3:51 pm Reply
  • Also, in my setup in view/__init__.py instead of

    from views import *
    from api_views import *

    I need to enter

    from .views import *
    from .api_views import *

    Said 02/06/2017 10:34 pm Reply
    • Yes this is probably because you’re on Python 3 and implicit relative imports like that won’t work. I’m on 2.7 and they work with it. Thanks for pointing that out. I’ll update the post to note this.

      codyparker 02/07/2017 1:12 pm Reply
  • on the page 2, it is very important to highlights this setting in the settings.py

    os.path.join(BASE_DIR, “static”),

    it is not something that is added by default if start project with django-admin tools

    Said 02/06/2017 9:37 pm Reply
    • Thanks, yes when I first talk about the settings file, I recommended overwriting all of the default code with what I show in the post. I’ll make sure that it’s more clear.

      codyparker 02/07/2017 5:17 pm Reply
  • Thanks, confirm MIDDLEWARE_CLASSES fixed the issue with ‘AsgiRequest’ object has no attribute ‘session’

    Said 02/06/2017 9:23 pm Reply
  • after following all instruction on the page 4, cannot login, getting this error

    AttributeError at /login/
    ‘AsgiRequest’ object has no attribute ‘session’
    Request Method: POST
    Request URL:
    Django Version: 1.9.12
    Exception Type: AttributeError
    Exception Value:
    ‘AsgiRequest’ object has no attribute ‘session’
    Exception Location: /home/gideon/virtualenvs/vEnv_my_obstruct_game/lib/python3.4/site-packages/django/contrib/auth/__init__.py in login, line 101
    Python Executable: /home/gideon/virtualenvs/vEnv_my_obstruct_game/bin/python
    Python Version: 3.4.3
    Python Path:
    Server time: Mon, 6 Feb 2017 15:53:42 +0000
    Traceback Switch to copy-and-paste view

    /home/gideon/virtualenvs/vEnv_my_obstruct_game/lib/python3.4/site-packages/django/core/handlers/base.py in get_response
    response = self.process_exception_by_middleware(e, request) …
    ▶ Local vars
    /home/gideon/virtualenvs/vEnv_my_obstruct_game/lib/python3.4/site-packages/channels/handler.py in process_exception_by_middleware
    return super(AsgiHandler, self).process_exception_by_middleware(exception, request)

    Said 02/06/2017 9:55 am Reply
    • One thing that could cause this with Django 1.9+ is if you have MIDDLEWARE instead of MIDDLEWARE_CLASSES in your settings.py file. Can you check that?

      codyparker 02/06/2017 10:28 am Reply
  • It seems there is an error in this instruction

    npm install –save-dev react react-dom webpack webpack-bundle-tracker babel-core babel babel-loadernpm babel-preset-es2015 react-websocket babel-preset-es2015 babel-preset-react jquery

    “babel-loadernpm” should read “babel-loader”

    Said Akhmedbayev 02/05/2017 11:28 pm Reply
    • Yep, you’re right – a little copy-paste issue on my part. It’s fixed now. Thanks for letting me know!

      codyparker 02/06/2017 9:06 am Reply
  • I have not yet finished your tutorial, but for what I see I can tell you huge THANK YOU!

    Said 02/05/2017 10:33 am Reply
    • Thank you, I hope it you find it useful. Please let me know if you have any issues!

      codyparker 02/06/2017 9:07 am Reply

Leave a Comment

Your email address will not be published. Required fields are marked *