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

@walltowall/gatsby-theme-ww-slice-studio

v0.1.18

Published

Gatsby theme providing an interactive playground for Prismic slices.

Downloads

10

Readme

@walltowall/gatsby-theme-slice-studio

Gatsby theme that provides interactive client documentation for Wall-to-Wall Gatsby websites.

Install

yarn add @walltowall/gatsby-theme-ww-slice-studio

How to use

Configure Gatsby

Setup the consuming project's gatsby-config as shown below:

// In your gatsby-config.js
plugins: [
  {
    resolve: '@walltowall/gatsby-theme-ww-slice-studio',
    options: {
      // Path to the project's root directory. This is required and should be set to __dirname.
      root: __dirname,

      // Name of the client for the site. Will appear throughout documentation.
      siteTitle: 'Site Title',

      // Provide an object of Prismic custom type JSON schemas to load into Gatsby.
      schemas,

      // Provide a list of layouts to show in the client documentation. Each named layout should have a corresponding
      // .js file in `/studio/layouts`.
      layouts: [
        'about',
        'design',
        'home',
        'project',
        'services',
        'recognition',
        'team',
      ],

      // Provide an object of Prismic custom types and slice zones. These keys should have corresponding entries
      // from the provided `schemas` object.
      sliceZones: {
        page: {
          description:
            'Each page document in Prismic represents a unique and visitable page on your website.',
          zones: {
            body:
              "Body slices comprise the majority of the content on it's respective page.",
          },
        },
      },
    },
  },
]

Configure Netlify & Authentication

Once your gatsby-config has been set-up, you'll need to configure a netlify.toml in your project root to serve the appropriate lambda functions for authentication. Below is the absolute minimum you'll need to configure lambda functionality.

[build]
  functions = "node_modules/@walltowall/gatsby-theme-ww-slice-studio/src/lambda"

After setting up your .toml file, ensure to add the appropriate environment variables to your Netlify site's dashboard. See .env for the values to enter.

Writing documentation

Layouts

As shown in the example gatsby-config, every defined layout will need to have a corresponding .js file in your project's /studio/layouts that follow the following structure:

export const LAYOUT_NAME = {
  // The display name for this layout.
  name: 'Name',

  // The custom type in Prismic this layout is available under.
  customType: 'page',

  // A short description for this layout.
  description: 'Sample description',

  // The list of slices to pre-populate the Prototyper when this layout is selected.
  // Must be a list of tuples containing the full slice name and the example index to render.
  example: [
    ['PageBodyHorizontalNavigation', 0],
    ['PageBodyFeaturedProjects', 0],
    ['PageBodyMixedSizedProjects', 0],
  ],

  // A list of zones to render in the layout documentation.
  // A zone can render any arbitrary JSX and label itself with a name and
  // reasoning.
  zones: [
    {
      // If you would like to render JSX without displaying any additional info,
      // e.g. rendering a <Header /> or <Footer />, just omit the `name`, property.
      render: () => <PageBodyHeader nextSharesBg={[true]} />,
    },
    {
      // Heading for the zone.
      name: 'Navigation',

      // If a zone is from a "preset", designate it as one with the `preset` property.
      // This will prevent this zone from being modified in the Prototyper tool.
      preset: 'Horizontal Navigation',

      // Client friendly reasoning as to why these slices were selected.
      reasoning:
        'Provides quick access to different project types for visitors.',

      // The actual JSX to render for this zone.
      render: () => (
        <PageBodyHorizontalNavigation
          title="design"
          rootHref="/"
          nextSharesBg={[true]}
        >
          <PageBodyHorizontalNavigation.Item href="/">
            Hospitality + Leisure
          </PageBodyHorizontalNavigation.Item>
          <PageBodyHorizontalNavigation.Item href="/">
            Interior Design
          </PageBodyHorizontalNavigation.Item>
          <PageBodyHorizontalNavigation.Item href="/">
            Office + Healthcare
          </PageBodyHorizontalNavigation.Item>
          <PageBodyHorizontalNavigation.Item href="/">
            Residential
          </PageBodyHorizontalNavigation.Item>
          <PageBodyHorizontalNavigation.Item href="/">
            Retail + Restaurants
          </PageBodyHorizontalNavigation.Item>
        </PageBodyHorizontalNavigation>
      ),
    },
    {
      name: 'Project Grid',

      // If a zone is not a preset, include the exact list of slices used in the example.
      slices: ['PageBodyFeaturedProjects', 'PageBodyBrandedCallout'],

      // In addition to the exact list, also provide a list of recommended slices for this zone.
      // In some designs, this may differ from `slices` since an example may not include every slice
      // that would be appropriate.
      recommendedSlices: [
        'PageBodyFeaturedProjects',
        'PageBodyMixedSizedProjects',
        'PageBodySmallProjects',
        'PageBodyBrandedCallout',
      ],
      reasoning:
        'Varied usage of the recommended slices helps give the layout a dynamic flow. The callout helps to provide a break in the list of projects.',
      render: () => (
        <>
          <PageBodyFeaturedProjects nextSharesBg={[true]}>
            <PageBodyFeaturedProjects.Project
              variant="large"
              imageURL="https://pvadev.cdn.prismic.io/pvadev/541704ba04a3f58caa4a37dd325d793d351dbd1d_0-flower-avenue.jpg"
              imageAlt="Example."
              location="Honolulu, Hawaii"
              categoryUID="residential"
              name="Flower Avenue"
              href={true}
            />
          </PageBodyFeaturedProjects>
          <PageBodyBrandedCallout
            variant="dark"
            textHTML="<h1>Our team of architects and interior designers is both collaborative and visionary.</h1>"
            buttonHref={true}
            buttonText="Our approach"
            nextSharesBg={[true]}
          />
          <PageBodyFooter />
        </>
      ),
    },
  ],
}

Once you have written all of your required layouts, create /studio/layouts/index.js in your project and export all of your layouts as named exports:

export { project } from './project'
export { otherLayout } from './otherLayout'

Slices

To write documentation for individual slices, create a docs object property on the slice component directly.

See below for an example:

export const PageBodyText = props => {
  // ... implementation details
}

// At the end of the file, add the `docs` object to the component.
PageBodyText.docs = {
  // The display name of the slice.
  name: 'Text',

  // List of examples of this slice. If a slice has variations of itself, each variant should be included.
  examples: [
    {
      // Name of the example. This will show in the prototyper tool.
      name: 'With Heading',

      // Corresponding JSX for this example.
      render: () => <PageBodyText />,
    },
  ],
}

General Documentation

To write additional general documentation, you can create additional markdown files in the /src/docs directory of this theme.

Each markdown file should have generally follow the following frontmatter:

---
parent: General
title: Images
path: general/images
summary: >-
  Short summary of article
---

List of Required Files

Due to the nature of aliased imports with webpack, below is a comprehensive list of required files that your project needs for this theme to function correctly:

  • src/index.css: Your fonts and base styles to inject into each Studio Frame.
  • src/slices/index.js: Export slicesMap as PageBody from
  • src/slices/PageBody: so our theme has alias access to it.
  • /netlify.toml: Must be configured to point to the theme's lambda folder. Ex: node_modules/@walltowall/gatsby-theme-ww-slice-studio/src/lambda
  • studio/layouts: Must contain your layouts and the appropriate index.js