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.
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!
- Install React Router
The Stormpath module is only compatible with React Router, so ensure that your application is using it.
- 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.
- 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;
- 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
});
- 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')
);
- 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} />
- 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>
- Show Elements When Logged In
Use the Authenticated
component:
<Authenticated>
<LogoutLink>Logout</LogoutLink>
</Authenticated>
- Hide Elements When Logged Out
Use the NotAuthenticated
component:
<NotAuthenticated>
<LoginLink>Login</LoginLink>
</NotAuthenticated>
- 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.