Neighbourhood Party Manager

    @last-rev/cli

    0.5.7 • Public • Published

    Installation

    NPM:

    npm install @last-rev/cli

    Yarn:

    yarn add @last-rev/cli

    Known Issues:

    1. Some setups will erquire you to run the following command to update your Path depending on where you have yarn installed
    export PATH="$(yarn global bin):$PATH"

    Usage

    last-rev {command} {...args}

    See below for specific command usage

    Commands

    cms-sync

    Description

    Syncs content from your CMS to the file system. Currently, only Contentful is supported.

    Usage

    Usage: cms-sync [options]
    
    Options:
      -d, --contentDir <content directory>        Directory in which to write synced files
      -c, --cms <string>                          CMS to sync  (default: "Contentful")
      --contentful-access-token <access token>    Contentful Access Token, defaults to env variable CONTENTFUL_ACCESSTOKEN
      --contentful-space-id <space id>            Contentful Space ID, defaults to env variable CONTENTFUL_SPACE_ID
      --contentful-host <contentful host>         Contentful host, defaults to env variable CONTENTFUL_HOST
      --contentful-env <contentful environement>  Contentful environment, defaults to env variable CONTENTFUL_ENV
      -h, --help                                  display help for command
    

    Detailed documentation

    By CMS:

    create-app

    Description

    This command will create an app from one of last-rev's example apps.

    The command will prompt you for the name of the new project, and will then authenticate you into github to access the lastrev-libraries repo.

    This will then do a couple things:

    1. Extract the contents of the example archive to the targeted directory
    2. Rename the packages based on the provided project name
    3. Create a github repo if one does not exist
    4. Create the netlify sites associated with the project
    5. Import content from a Contentful starter space.

    Best Practices

    The best way to use this utility is to do everything all at once.

    • Create an empty contentful space
    • Do not use an existing github repo, the app will do that for you.
    • Do not set up the netlify sites, the app will do that for you.

    Preparation

    Prerequisite, Create a New Space in Contentful for the site

    1. Go to Contentful and login
    2. Click on your organization in the upper left corner of the screen
    3. Choose "Add a Space" to your organization and follow the instructions

      NOTE: If this is a new customer project you can use our Last Rev organization and create a new Partner Project Space. Fill out the information and give it a launch date 6 months in the future.

    Important: If you do not do the contentful import from this CLI, you will need to create the following content items for your project to build correctly (but please try to avoid this, and use the CLI to do that instead.)

    1. Site (You must add this content entry ID to your .env file) example: DEFAULT_SITE_ID=10Gmpgoe7XdTwGmwXAyzah
    2. At least one page
    3. Header (added to the Site) item

    Prerequisite, Gather the information needed to create the app.

    1. The Space ID and environment of your new contentful space
    2. The Space ID and environment of the space you want to import content from
    3. The Team slug of the netlify account you want to creat the sites in
    4. The Redis host/port/password of the redis instance you want to use (or leave these blank for now)
    5. The slug of the github organization you want to create the repo in, or the org/name of the existing repo you want to use
    6. The Google Tag Manager ID of the GTM you want to use (or leave it blank for now)

    Steps

    1. Create the directory for the new project: mkdir {project-name}
    2. CD into the directory: cd {project-name}
    3. Run last-rev create-app. - This will create a sample create-app.json in the directory. The JSON represents the simplest possible configuration for the app. (see below for more configuration options)
    4. Edit the create-app.json file to add in your app-specific configuration.
    5. Run last-rev create-app again. Since the JSON exists, this will run the app creation and other steps according to the JSON.
    6. If you have not previously connected with different third party services (Netlify, Github, Contentful), you will be walked through the process to do this.
    7. At this point, all processes will run. At the end, you will see some output messages telling you information about the app.

    Running Locally

    1. run nvm install && nvm use && yarn to install the dependencies and get the project to a running state.
    2. run yarn propagate-env && yarn build to do an initial build of the app.
    3. You are now ready to serve the built site (yarn serve) or run it in dev mode yarn dev.

    Running locally: instructions here

    IMPORTANT: Prior to loading the dev site in the browser, you will have to prime the redis cache by making a change to a piece of content in Contentful. Otherwise, the site will load, but you will see no content. This is due to a known issue that should be fixed in the future.

    JSON configuration

    Below are the full JSON configuration options:

    {
      // Configuration for creating the app. Leave this empty if you have already
      // created the app and just want to run the other parts of the command.
      // Drop this element if you just want to run one of the other processes
      app: {
        // project name, required.
        name: string;
        // defaults to lastrev-next-starter
        starter: string;
        // Space ID of the target contentful space you will be using in this app, required.
        contentfulSpaceId: string;
        // Name of the target contentful environmnent you will be using in this app, defaults to "master".
        contentfulEnv: string;
        // Repo name of the github repo to use for this app.
        // Used for creating the repo, but if one exists already, that will be used
        // and a new one will not be created. Some steps will be skipped, however.
        // If a repo name is not provided, will default to app.name
        repoName: string;
        // The owner of the github repo. Generally should be an organization, but could be your personal account name.
        // the github repo is a combination of name and owner
        // if an owner is not provided, the current logged in user will be used.
        repoOwner: string;
    
        // Only needed if netlify dev site is not being created as part of this run
        // The Domaibn URL of the netlify dev site
        // Will be used to set up the contentful webhooks for the app
        devDomainUrl: string;
      };
      // A redis user configured with access to only the current space. Usually this will be created as part of the create-app process and should be omitted. But if a user has already been created, provide the info below
      redis: {
        // The redis host to use for the app. Required if providing any config for the redis section.
        host: string;
        // The redis port to use for the app. Required if providing any config for the redis section.
        port: number;
        // The redis password to use for the app. Required if providing any config for the redis section.
        password: string;
        // The redis username to use for the app. Required if providing any config for the redis section.
        username: string;
      };
      // Configuration to set up your netlify sites. Leave this empty if you have already
      // created the sites and just want to run the other parts of the command
      // If you are running this separately from the app creation process, you will need to
      // provide at least on of devSiteName/prodSiteName/storybookSiteName.
      // drop this element if you do not want to create the netlify sites.
      netlify: {
        // The slug of the netlify account to use for this app.
        // You can get this from the URL when you are on the team page:
        // https://app.netlify.com/teams/{this is the slug}/overview
        // This is required
        accountSlug: string;
        // The name of the netlify develop site to create.
        // required if app is not being created at the time of this run,
        // otherwise defaults to {app-name}-dev
        devSiteName: string;
        // The name of the netlify production site to create.
        // required if app is not being created at the time of this run,
        // otherwise defaults to {app-name}-prod
        prodSiteName: string;
        // The name of the netlify storybook site to create.
        // required if app is not being created at the time of this run,
        // otherwise defaults to {app-name}-storybook
        storybookSiteName: string;
      };
      // Configuration for importing contentful entries/models/assets/extensions
      // drop this element if you do not wish to do this as part of this run.
      contentfulImport: {
        // The ID of the Contentful space to import from. Required.
        sourceSpaceId: string;
        // The name of the Contentful environment to import from. will default to "master".
        sourceEnv: string;
        // The ID of the Contentful space to import into.
        // If you are creating an app as part of this run, leave this blank,
        // the spaceId from that config will be used.
        targetSpaceId?: string;
        // The name of the Contentful environment to import into.
        // If you are creating an app as part of this run, leave this blank,
        // the spaceId from that config will be used.
        // otherwise, will default to "master"
        targetEnv: string;
        // set this to true if you want to skip importing the contentful content types.
        // at least one of these next three fields must be false
        // defaults to false
        skipContentTypes: boolean;
        // set this to true if you want to skip importing the contentful entries.
        // defaults to false
        skipEntries: boolean;
        // set this to true if you want to skip importing the contentful assets.
        // defaults to false
        skipAssets: boolean;
        // set this to true if you want to skip importing the contentful UI Extensions.
        // defaults to false
        skipExtensions: boolean;
      };
    };

    develop

    Description

    A utility to help set up and restore development environments to use lastrev-libraries locally against a client project.

    Usage

    Usage: develop [options] [command]
    
    Options:
      -h, --help           display help for command
    
    Commands:
      configure [options]  Configure the monorepo in the current directory to run with some local lastrev libraries
      info                 Show information about the current development environment
      restore              Restore the current project to use no local lastrev libraries
      fix                  Fix the current development environment
      help [command]       display help for command
    
    

    gen-fragments

    Description

    Generates fragments from a contentful configuration.

    Usage

    Usage: gen-fragments [options]
    
    Options:
      -i --input-dir <Input Directory>                            Path to a directory with contentJson files
      -o --output-dir <Output Directory>                          Path to a directory where generated files will be written
      -e --contentful-environment <Contentful Environment>        Contentful environment to use, defaults to CONTENTFUL_ENV environment variable, or "master" (default: "master")
      -t --contentful-delivery-token <Contentful Delivery Token>  Contentful delivery access token, defaults to CONTENTFUL_DELIVERY_TOKEN environment variable
      -s --contentful-space-id <Contentful Space ID>              Contentful space ID, defaults to CONTENTFUL_SPACE_ID environment variable
      -l, --link-content-type <Link Content Type ID>              The ID of the Link or Element Link content type to convert
      -h, --help                                                  display help for command
    

    gql-serve

    Description

    Starts the last-rev graphql server. This will generate a default schema based on the types in your CMS (Currently, only Contentful is supported).

    If an optional extensions directory is passed in, all files in that directory will be loaded and the extensions will be read in. See below for expected file format

    Usage

    Usage: gql-serve [options]
    
    Options:
      -c, --config <config file>                          Path to a config file

    Example:

    last-rev gql-serve -e graphql/extensions -c graphql/config

    Config File

    The config file should be a javascript file exporting the following values:

    {
      // optional parsed extensions
      extensions: {
        typeDefs, // am optional string or documentnode with defined typeDefs
        resolvers, // an optional resolvers object
        mappers, // an optional mappers object
        typeMappings, // an optional typeMappings object
        pathsConfigs, // an optional paths config object
      },
      // optional directory pointing to individual files containing extensions
      // will only be read if "extensions" is not defined
      // path should be relative to the config file
      extensionsDir,
      // optional cms to use. Currently only "Contentful" supported
      // defaults to "Contentful"
      cms,
      // optional port. Defaults to 5000
      port,
      // optional hostname. Server will be started on localhost if not provided
      host,
      // reqiured: the directory where content JSON files are located
      // path should be relative to the config
      contentDir
    }

    Server Documentation

    See @last-rev/graphql-contentful-core for server documentation.

    Developing locally

    1. Install nodemon globally, if not installed already
    npm install -g nodemon
    1. Compile the code in watch mode
    yarn dev
    1. In a separate terminal window, navigate to the root of the project you want to run the server in
    cd dev/my-other-project
    1. Using nodemon, run the server, using the relative path of the last-rev bin file, and point it to watch the packages directory of the monorepo
    nodemon -x '../lastrev-libraries/packages/cli/bin/last-rev gql-serve -c graphql/config' -w ../lastrev-libraries/packages
    1. Any time a change is made in the monorepo, the server will restart automatically. If you want to also restart when the extensions directory changes, you can either just type rs in the terminal running nodemon, or add the directory to the nodemon watch argument

    Developing New Commands

    1. Create a new directory/folder in /src/commands and name it what you want the new command to be called

    2. Create a new file (.ts) in the new directory/folder you created in step 1

    3. Create your new command using the commander package

    • Look at cms-sync.ts as a simple example
    1. Add new command to /src/index.ts file
    • Example:
      .command('new-command', 'Description of new command', {
        executableFile: resolve(__dirname, '../dist/new-command.js')
      })
    1. Add new command's path to rollup.config.js file
    • Example:
      './src/commands/new-command/new-command.ts'
    1. Test command locally
    • Run in dev mode
      • Example:
        yarn dev --scope=@last-rev/cli
    • Open new terminal and run which last-rev
      • This will show you which last-rev library version you are using
        • If it is not your local version then export it
          • Example:
            export PATH=/Users/anthonywhitley/repos/lastrev-libraries/packages/cli/bin:$PATH
    • You should now be able to test your new command by running last-rev <new-command> in the same terminal session

    Keywords

    none

    Install

    npm i @last-rev/cli

    DownloadsWeekly Downloads

    595

    Version

    0.5.7

    License

    ISC

    Unpacked Size

    282 kB

    Total Files

    78

    Last publish

    Collaborators

    • maxtechera.lastrev
    • tharris
    • justinlastrev
    • jaimelastrev
    • bradtaylorsf