Skip to content

SachaG/SidebarVulcan

Repository files navigation

Sidebar

This is the codebase for Sidebar, a daily newsletter of design-related links. It's built with Vulcan.js, a full-stack React/GraphQL framework.

This app is used both to display links, accept link submission, and subscribe users to the mailing list; as well as to moderate the link queue and schedule newsletters.

Should I Use This?

If you intend to use this codebase as a starting point for your own project, in addition to basic HTML/CSS knowledge you should already be familiar with React at the very least, and ideally have a basic understanding of how GraphQL works (or be willing to learn). Being familiar with Node is also a plus.

Note that this is a production codebase for a real-world app, and as such being easy to customize or adapt is not its first priority. Be ready to have to get your hands dirty to change a lot of the design, content, behavior, etc. if you want to reuse this for your own project.

License

This codebase is provided mainly for educational purposes, but it is MIT-licensed meaning that you can freely reuse parts of all of it for your own projects, including commercial applications.

Note that this only applies to code. All graphic assets, color palettes, text content, images, logos, etc. are not MIT-licensed and should not be reused. So if you do want to use the code, please take the time to remove or change these assets.

Installation

1. Two-Repo Install

Please follow the Vuclan two-repo install to get the latest version of Vulcan's devel branch.

2. Install NPM packages

Install NPM packages with yarn or npm install.

3. Create your settings.json file

Create a new settings.json file at the root of your project and copy over the contents of settings-sample.json.

At minimum, you will need to configure the settings with a Twitter API key to enable Twitter login. Note that your settings will not be publicly accessible unless they are within the public block of the JSON object, in which case they will be published to the client.

4. Run the app

Run the app with:

npm start

Settings

You will need your own settings.json file. You can check out the included settings-sample.json file and use it as a starting point.

Main Features

The Sidebar app is divided into two main parts.

Public-Facing Site

This is what users have access to on Sidebar. The main features include:

  • A list of recent links on the homepage.
  • Link archives.
  • Newsletter sign-up widget.
  • Sponsorship sign-up flow.
  • Link submission page.

Admin Area

The admin area is used to moderate links and send out newsletters. It includes:

  • A link (a.k.a. posts) moderation dashboard.
  • A newsletter scheduling dashboard.
  • Other dashboards for users, categories, discounts, etc.

Screencasts

If you're looking for a quick overview of the codebase, screencasts are available on YouTube.

Code Overview

All code for the Sidebar app is contained within the sidebar2020 package. It's split into three sub-directories corresponding to the environment the code will run into: client, server, and both (the modules directory), plus a components directory (components also run in both environments).

The codebase generally follows a feature-first organization, meaning that all code related to a specific feature (posts, categories, users, etc.) is grouped together rather than grouping code by what it actually does (GraphQL code, cron jobs, models, etc.).

File Types

The majority of files in this codebase follow the same naming convention. Here is a quick overview.

Name Description
main.js The entry point for the client or server bundle
index.js Centralizes all the imports in a directory
collection.js Create or extend a collection (a.k.a. model)
schema.js A model's schema (list of fields)
helpers.js Various helpers related to a model
callbacks.js Server-side callbacks that should run before or after a given model's CRUD mutations
apischema.js A model's API-only (i.e. not present in the database) fields
fragments.js Fragments are a way to control what fields to load when requesting data

Feature Index

Here is a cross-reference of the various Vulcan features used in the app and where the corresponding code lives.

Components

Feature/API Location
useQuery PostHome.jsx
Cell PostCell.jsx
Datatable AdminPosts.jsx
SmartForm PostSubmit.jsx, SponsorSubmit

Modules (Client/Server)

Feature/API Location
Schema definition schema.js
Field-specific query schema.js
onCreate, onUpdate callbacks schema.js
Field decorator (makeAutocomplete) schema.js
Field relations schema.js
Custom input schema.js, ScheduledAtInput.jsx
Fragment definition fragments.js
addToFragmentMatcher graphql.js
extendCollection collection.js
Routes (with layoutComponent and access control) routes.js

Server

Feature/API Location
Cache cache.js
Cron cron.js
DB Indexes indexes.js
apiSchema apischema.js
Callbacks callbacks
Custom mutations mutations.js
Custom queries queries.js
RSS feed rss.js
REST API api.js
Emails emails.js
GraphQL Union Type graphql.js

Integrations

The app relies on a few external service providers:

Note that missing the API keys (in your settings.json file) for one or more of these services might lead to errors and/or warnings that might prevent you from running the app properly.

Support

Although this codebase is provided as-is without any guarantees of support, you can ask questions in the Vulcan Slack.

About

The Sidebar Vulcan.js repository

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published