Skip to content

starcount/stormpath-sdk-react

 
 

Repository files navigation

Stormpath React SDK

Bower Version Build Status

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

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. Configure Stormpath

In your application directory, create a file named stormpath.yml with the contents below:

client:
  apiKey:
    id: YOUR_API_KEY_ID
    secret: YOUR_API_KEY_SECRET
  application:
    href: https://api.stormpath.com/v1/applications/XXXX <-- YOUR APP HREF
  1. Install React Router

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

  1. 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.

  1. 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;
  1. 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({
  // See the API docs for available configuration options.
});
  1. 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';
import { Route, browserHistory } from 'react-router';

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

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

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

Now we have most of our routes setup, let's add the route to redirect to when we've logged out.

<HomeRoute path='/' component={HomePage} />

Add an additional HomeRoute and wrap it inside an AuthenticatedRoute to specify the route to redirect to when signing up or logging in. If this is left out then the first unauthenticated HomeRoute is used.

<AuthenticatedRoute>
  <HomeRoute path='/profile' component={ProfilePage} />
</AuthenticatedRoute>
  1. 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 end the session and navigate to your specified HomeRoute.

<LogoutLink>Logout</LogoutLink>
  1. Show Elements When Logged In

Use the Authenticated component:

<Authenticated>
  <LogoutLink>Logout</LogoutLink>
</Authenticated>
  1. Hide Elements When Logged Out

Use the NotAuthenticated component:

<NotAuthenticated>
  <LoginLink>Login</LoginLink>
</NotAuthenticated>
  1. User State in Components

Access user state in your components by requesting the authenticated and user context types:

class ContextExample extends React.Component {
  static contextTypes = {
    authenticated: React.PropTypes.bool,
    user: React.PropTypes.object
  };

  render() {
    if (!this.context.authenticated) {
      return (
        <div>
          You need to <LoginLink />.
        </div>
      );
    }

    return (
      <div>
        Welcome {this.context.user.username}!
      </div>
    );
  }
}
  1. 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.

Documentation

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

Example

See the example app.

Browserify

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"
}

Help

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 support@stormpath.com or visit our support center.

Contributing

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

License

Apache 2.0, see LICENSE.