This module provides routes and components for React that will allow you to solve common user management tasks using Stormpath, such as login and signup.

Stormpath is a User Management API that reduces development time with instant-on, scalable user infrastructure. Stormpath's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.

• Getting Started
• Documentation
• Example
• Help
• Contributing
• License

Follow these steps to add Stormpath user authentication to your React app.

Don't have an app? Use our example app as a boilerplate - it has Stormpath already integrated!

1. Install React Router

The Stormpath module is only compatible with React Router, so ensure that your application is using it.

2. Integrate Your Back-End

This module requires Stormpath on your back-end to work properly. At the moment we have a fully-featured integration for Express.js, express-stormpath.

For a quick setup, use our Stormpath SPA Development Server.

3. Install the SDK

Download and include stormpath-sdk-react.min.js in your index.html file.

<script src="stormpath-sdk-react.min.js"></script>

Or install with bower:

$ bower install react-stormpath --save

Or install with npm:

$ npm install react-stormpath --save

Then depending on how you load the library, access it as shown below:

// Using an ES6 transpiler, like Babel.
import ReactStormpath, { Router, AuthenticatedRoute, LoginLink } from 'react-stormpath';

// Or not using an ES6 transpiler.
var ReactStormpath = require('react-stormpath').default;
var Router = require('react-stormpath').Router;
var AuthenticatedRoute = require('react-stormpath').AuthenticatedRoute;
var LoginLink = require('react-stormpath').LoginLink;

// Or if you are using it from a browser without UMD.
var Router = ReactStormpath.Router;
var AuthenticatedRoute = ReactStormpath.AuthenticatedRoute;
var LoginLink = ReactStormpath.LoginLink;

4. Initialize the SDK

Before calling React.render() be sure to call ReactStormpath.init(). This sets up the SDK so that it's ready to be used.

ReactStormpath.init({
  // Optional: Set if you want to use your own Flux dispatcher.
  dispatcher: instanceOfYourFluxDispatcher
});

5. Configure the Router

In the file where you setup your React Router routes, change your ReactRouter.Router to ReactStormpath.Router as shown below:

import { Router } from 'react-stormpath';

ReactDOM.render(
  <Router history={browserHistory}>
    <Route path='/' component={MainPage} />
  </Router>,
  document.getElementById('app-container')
);

6. Setup your Routes

Start by adding a route that people can go to in order to sign up. This will just be a regular ReactRouter.Route. Then once you've done this, create a view for your route called RegistrationPage and add the RegistrationForm component to it. This will render a registration form and allow people to sign up.

<Route path='/register' component={RegistrationPage} />

Now when we have our registration done, let's add a LoginRoute so that our users can log in. This route is special, since it tells the router where to go when you access a AuthenticatedRoute without being authenticated. Once you've added the route, create a view for your route called LoginPage and add the LoginForm component to it. The LoginForm component will render a username and password login form so that your users can log in.

<LoginRoute path='/login' component={LoginPage} />

Once you've added a LoginRoute, let's add a LogoutRoute. The LogoutRoute is merely a route handler that ends your session, so you don't need to add any view for it.

<LogoutRoute path='/logout' />

Then on all routes that you want to protect, use AuthenticatedRoute.

<AuthenticatedRoute path='/protected' component={ProtectedPage} />

7. Add Login and Logout Links

Use the LoginLink component to create a link that will navigate your users to the LoginRoute route:

<LoginLink>Login</LoginLink>

Use the LogoutLink component to navigate your users to the LogoutLink route and thereby end your session:

<LogoutLink>Logout</LogoutLink>

8. Show Elements When Logged In

Use the Authenticated component:

<Authenticated>
  <LogoutLink>Logout</LogoutLink>
</Authenticated>

9. Hide Elements When Logged Out

Use the NotAuthenticated component:

<NotAuthenticated>
  <LoginLink>Login</LoginLink>
</NotAuthenticated>

10. That's It!

You just added user authentication to your app with Stormpath. See the API Documentation for further information on how Stormpath can be used with your React app.

For all available routes and components, see the API Documentation.

See the example app.

This module can be used with Browserify. Please add the following lines to your package.json file:

"browser": {
  "stormpath": "./node_modules/react-stormpath/dist/stormpath-sdk-react.min.js"
}

If you have an issue while integrating this library, please make sure to look at the open issues on this repository.

You may also contact us via email at [email protected] or visit our support center.

Found something you want to change? Please see the Contribution Guide, we love your input!

Apache 2.0, see LICENSE.