npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@unchainedshop/gatsby-theme-apollo-core

v3.0.26

Published

A theme for bootstrapping Gatsby websites at Apollo

Downloads

8

Readme

gatsby-theme-apollo-core

This is the base theme for building Apollo-branded Gatsby sites. It contains a small amount of configuration, and a handful of components that make it easy to build consistent-looking UIs.

It comes with a few Gatsby plugins:

Installation

$ npm install gatsby gatsby-theme-apollo-core

Configuration

// gatsby-config.js
module.exports = {
  plugins: ['gatsby-theme-apollo-core'],
  siteMetadata: {
    title: 'Apollo rocks!',
    description: 'Gatsby themes are pretty cool too...'
  }
};

Components and utilities

All of the React components and utilities documented here are available as named exports in the gatsby-theme-apollo-core package. You can import them like this:

import {MenuButton, Sidebar, breakpoints} from 'gatsby-theme-apollo-core';

Layout

Layout should wrap every page that gets created. It configures React Helmet and sets the meta description tag with data from the siteMetadata property in your Gatsby config.

import {Layout} from 'gatsby-theme-apollo-core';

function MyPage() {
  return (
    <Layout>
      Hello world
    </Layout>
  );
}

| Prop name | Type | Required | | --------- | ---- | -------- | | children | node | yes |

Sidebar

A component that renders a sidebar with a LogoTitle component in the top left corner. It can also be configured to collapse into the left side of the page on narrow windows.

import {Layout, Sidebar} from 'gatbsy-theme-apollo';

function MyPage() {
  return (
    <Layout>
      <Sidebar>
        Sidebar content goes here
      </Sidebar>
    </Layout>
  );
}

| Prop name | Type | Required | Description | | ---------- | ------ | -------- | -------------------------------------------------------------------------------- | | children | node | yes | | | responsive | bool | no | If true, the sidebar will behave as a drawer absolutely positioned on the left | | open | bool | no | Controls the sidebar visibility when the responsive prop is true | | logoLink | string | no | The URL/path that the sidebar logo should link to |

SidebarNav

A configurable two-tiered, expandable/collapsible navigation component for use in conjunction with the Sidebar component above. It accepts a contents prop that defines what links and collapsible sections get rendered. Here's an example of the expected shape of a contents prop:

const contents = [
  {
    title: 'Getting started',
    path: '/'
  },
  {
    title: 'External link',
    path: 'https://apollographql.com',
    anchor: true
  },
  {
    title: 'Advanced features',
    pages: [
      {
        title: 'Schema stitching',
        path: '/advanced/schema-stitching'
      }
    ]
  }
];

Each element in the array can have title, path, pages, and anchor props. pages is an array of more elements with the same shape. By default, a Gatsby Link component will be used to render the links, but you can use a regular HTML anchor tag (<a>) by passing the anchor property to true on any page object.

The SidebarNav component gives the currently selected page an "active" style, and if it's a subpage, it will keep the currently active section expanded. To facilitate this, you must pass the current path to the pathname prop. Luckily, Gatsby exposes this in the location prop that gets passed automatically to every page!

import {Layout, Sidebar, SidebarNav} from 'gatsby-theme-apollo-core';

function MyPage(props) {
  return (
    <Layout>
      <Sidebar>
        <SidebarNav
          contents={contents}
          pathname={props.location.pathname}
        />
      </Sidebar>
    </Layout>
  );
}

| Prop name | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------------------------------------- | | contents | array | yes | An array of items to render | | pathname | string | yes | The current path (props.location.pathname expected) | | alwaysExpanded | bool | no | If true, all collapsible sections are expanded and cannot close |

ResponsiveSidebar

A render props component that manages the state for responsive sidebars. On mobile devices, the sidebar is opened by a MenuButton component, and dismissed when the user clicks away from the sidebar. This component's children prop accepts a function that provides values and functions to enable this behavior easily.

import {
  Layout,
  Sidebar,
  ResponsiveSidebar,
  FlexWrapper,
  MenuButton
} from 'gatsby-theme-apollo-core';

function MyPage() {
  return (
    <Layout>
      <ResponsiveSidebar>
        {({sidebarOpen, openSidebar, onWrapperClick, sidebarRef}) => (
          <FlexWrapper onClick={onWrapperClick}>
            <Sidebar responsive open={sidebarOpen} ref={sidebarRef}>
              This is a sidebar
            </Sidebar>
            <MenuButton onClick={openSidebar} />
          </FlexWrapper>
        )}
      </ResponsiveSidebar>
    </Layout>
  );
}

| Prop name | Type | Required | Description | | --------- | ---- | -------- | ----------------------------------------------------------- | | children | func | yes | A render prop-style function that returns a React component |

Logo

A component that renders the Apollo logo. This logo can be removed or replaced using component shadowing.

import {Logo} from 'gatsby-theme-apollo-core';

function MyPage() {
  return <Logo />;
}

Customizing the logo

Through component shadowing, you can override the logo that gets shown. Simply create a file that exports a SVG React component in your theme consumer at src/gatsby-theme-apollo-core/components/logo.js.

// src/gatsby-theme-apollo-core/components/logo.js
export {ReactComponent as default} from '../../assets/custom-logo.svg';

Check out this CodeSandbox link for a full component shadowing example.

Edit Component shadowing example

| Prop name | Type | Required | Description | | --------- | ---- | -------- | ------------------------------------ | | noLogo | bool | no | If true, the Apollo logo is hidden |

Colors

An object mapping semantic names to hex strings. All of these colors are drawn from Space Kit. You can use this utility to write CSS-in-JS rules like this:

import {colors} from 'gatsby-theme-apollo-core';

const StyledButton = styled.button({
  color: colors.primary,
  background: colors.background
});

Customizing colors

You can override the default color palette using shadowing. The only constraint is that the primary and secondary palette keys must be colors from Space Kit. Here's an example of a shadowed color palette:

// src/gatsby-theme-apollo-core/utils/colors.js
const {colors} = require('gatsby-theme-apollo-core/src/utils/colors');
const {colors: spaceKitColors} = require('@apollo/space-kit/colors');

exports.colors = {
  ...colors,
  primary: spaceKitColors.red.base,
  divider: '#aeaeae'
};

You can refer to the default colors file for palette keys that can be customized.

Breakpoints

A mapping of size keys to media queries. This is useful for writing responsive CSS-in-JS components.

import {breakpoints} from 'gatsby-theme-apollo-core';

const StyledMenu = styled.nav({
  fontSize: 24,
  [breakpoints.lg]: {
    fontSize: 20
  },
  [breakpoints.md]: {
    fontSize: 16
  },
  [breakpoints.sm]: {
    fontSize: 12
  }
})

| Key | Value | | --- | -------------------------- | | sm | @media (max-width: 600px) | | md | @media (max-width: 850px) | | lg | @media (max-width: 1120px) |

Deploying to a subdirectory

In order to deploy a Gatsby site to a subdirectory, there are a few extra steps to take. First, you must provide a pathPrefix property in your Gatsby config. This option combined with the --prefix-paths option in the Gatsby CLI will handle most of the hard work. Read more about path prefixing in Gatsby here.

// gatsby-config.js
module.exports = {
  ...
  pathPrefix: '/YOUR_PATH_PREFIX'
};

Now, when you run npx gatsby bulid --prefix-paths, all pages, references to static assets, and links between pages will be prefixed with your custom path. That means that if you made a page with the path /about, it will live at /YOUR_PATH_PREFIX/about. In order for this to work within our server configuration, your website files also must exist in a directory with the same name. Here's how this sequence of events would look if you ran commands in your terminal:

$ npx gatsby build --prefix-paths
$ mkdir -p YOUR_PATH_PREFIX
$ mv public/* YOUR_PATH_PREFIX
$ mv YOUR_PATH_PREFIX public/

We use Netlify to deploy our websites, so to express this slightly more complicated build process to them, create a netlify.toml file that follows this pattern:

# netlify.toml
[build]
  base = "/"
  publish = "public/"
  command = "gatsby build --prefix-paths && mkdir -p YOUR_PATH_PREFIX && mv public/* YOUR_PATH_PREFIX && mv YOUR_PATH_PREFIX public/"

We use Fly to manage our server rewrites and redirects. To point your new Netlify deployment to a page on apollographql.com, first create a new backend using your site's Netlify alias. Next, you'll need to add two rewrite rules:

  • /YOUR_PATH_PREFIX/:page ➡️ /YOUR_PATH_PREFIX/$page
  • /YOUR_PATH_PREFIX ➡️ /YOUR_PATH_PREFIX

Be sure to set the priority of each of these rules to 3, or a value lower than the top two redirect rules that apply to our website root. Once these rewrite rules take effect, your site will be live at https://apollographql.com/YOUR_PATH_PREFIX.

Examples

License

MIT