lookbook 0.7.4 → 0.8.0.beta.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96f31c2b265d871a152627dfb10b0c0e1f6db8ae42e811abfeb138c7bf45d806
-  data.tar.gz: 9ae695f9a3fc7c28bd5a7fbf77fc0959d92d46661525e7593961555cd41d76fb
+  metadata.gz: aa9a6048a7c6da30fcf5fe7c42a0a41365c3964da88d1d639a640c1acdd97a95
+  data.tar.gz: dbbf4e04289ccadde4f37453123aabc70d982104b6933b3e139b0c65ea2a68f4
 SHA512:
-  metadata.gz: 8b658dc2f0e2b7213761be9197f916594381319927f02097c3901af13d9c35194e45d568d70a21c3da05407ea79e589ffa1c3530905c73dc5cbfa1100cc2ac3f
-  data.tar.gz: 55bc108c5a1ee957970709efe01c75956ee7b925043bab7b5c6aba1bafa1f998191d7872a7e08ddbd85daad2d7713437ec9340c8f2273568ecffa17bbb78a738
+  metadata.gz: a9eea08255c6263b84d6212d88d4a08ac425377eb1b0f42e4c5e626e04e1281e711c3ba41df98b550e3777b4e292824884ecd5e05b733db97126ccb6ba4cd100
+  data.tar.gz: 8b48c299198427e2e957eb6c3dcccf6ae1544a921ef5ae4ba37fad558dd0274a1f864e9b8a37fb5b76a49c275f74f5a73e3363a8c6c4d4092a380639b99798e8

data/README.md

@@ -13,7 +13,7 @@
 ---
 
 <div align="center">
-<a href="#installing">Installing</a> • <a href="#previews">Previews</a>  • <a href="#pages">Pages</a> • <a href="#config">Configuration</a> 
+<a href="#installing">Installing</a> • <a href="#previews">Previews</a>  • <a href="#pages">Pages</a> • <a href="#deployment">Deployment</a> • <a href="#config">Config</a> 
 </div>
 
 ---
@@ -72,13 +72,6 @@ The `at` property determines the root URL that the Lookbook UI will be served at
 
 Then you can start your app as normal and navigate to `http://localhost:3000/lookbook` (or whatever mount path you specified) to view your component previews in the Lookbook UI.
 
-#### Mounting in Production
-
-If you would like to expose the Lookbook UI in production as well as in development
-
-1. Remove the `if Rails.env.development?` condition from around the mount statement in `routes.rb`
-2. Add `config.view_component.show_previews = true` to `config/environments/production.rb`
-
 
 <h2 id="previews">Previews</h2>
 
@@ -687,6 +680,73 @@ Default: `pages`
 config.lookbook.page_route = `docs`
 ```
 
+<h2 id="deployment">Deploying in Production</h2>
+
+Lookbook is intended to be a tool for aiding the ViewComponent development process, and so is usually restricted to running only when the app is in `development` mode.
+
+However, it is possible to run Lookbook in a production environment if you wish.
+
+### Differences between development and production
+
+By default, Lookbook will behave a little differently in production than it does in development:
+
+1. Watching files for changes is disabled
+2. Parsing preview files for annotations does **not** happen at runtime. Instead the preview files must be pre-parsed via a Rake task before starting the app (much like asset precompilation).
+
+### Pre-parsing preview files
+
+Run the following command to pre-parse the preview files annotations:
+
+```
+rake lookbook:previews:preparse
+```
+
+If you wish to run this as part of your existing assets precompilation step, you can add the following into your app's `Rakefile`:
+
+```ruby
+Rake::Task['assets:precompile'].enhance do
+  Rake::Task["lookbook:previews:preparse"].invoke
+end
+```
+
+The pre-parsing of preview files will then take place every time `rake assets:precompile` is called and so will not need to be run separately.
+
+### Configuration changes for production
+
+You will also need to make sure that the following configuration changes have been made when deploying to production:
+
+1. Make sure ViewComponent is [configured to show previews in production](https://viewcomponent.org/api.html#show_previews) (by default it is disabled when not in development):
+
+```ruby
+# config/environments/production.rb
+config.view_component.show_previews = true
+```
+
+2. Remove any environment checking from around the Lookbook mounting declaration (if added as per install instructions):
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # if Rails.env.development? <- remove
+    mount Lookbook::Engine, at: "/lookbook"
+  # end
+end
+```
+
+### Overriding production default behaviours
+
+If for some reason you wish to enable file watching or runtime preview annotation parsing in production, you can always override the default behaviour using thie following config options:
+
+```ruby
+# config/environments/production.rb
+
+# enable file-change listening
+config.lookbook.listen = true 
+
+# enable runtime preview parsing
+config.lookbook.runtime_parsing = true 
+```
+
 <h2 id="config">General Configuration</h2>
 
 Lookbook will use the ViewComponent [configuration](https://viewcomponent.org/api.html#configuration) for your project to find and render your previews so you generally you won't need to configure much else separately.

data/app/controllers/lookbook/previews_controller.rb

@@ -145,7 +145,6 @@ module Lookbook
     def preview_controller
       return @preview_controller if @preview_controller.present?
       controller_class = Lookbook.config.preview_controller.constantize
-      controller_class.class_eval { include Lookbook::PreviewController }
       controller = controller_class.new
       controller.request = request
       controller.response = response

data/lib/lookbook/engine.rb

@@ -49,6 +49,7 @@ module Lookbook
       options.preview_srcdoc = false if options.preview_srcdoc.nil?
       options.preview_display_params ||= {}.with_indifferent_access
 
+      options.listen = Rails.env.development? if options.listen.nil?
       options.listen_paths = options.listen_paths.map(&:to_s)
       options.listen_paths += options.preview_paths
       options.listen_paths << (vc_options.view_component_path || Rails.root.join("app/components"))
@@ -57,6 +58,9 @@ module Lookbook
       options.cable_mount_path ||= "/lookbook-cable"
       options.cable_logger ||= Rails.logger
 
+      options.runtime_parsing = !Rails.env.production? if options.runtime_parsing.nil?
+      options.parser_registry_path ||= Rails.root.join("tmp/storage/.yardoc")
+
       options.experimental_features = false unless options.experimental_features.present?
     end
 
@@ -72,32 +76,47 @@ module Lookbook
     end
 
     config.after_initialize do
-      @preview_listener = Listen.to(*config.lookbook.listen_paths, only: /\.(rb|html.*)$/) do |modified, added, removed|
-        begin
-          parser.parse
-        rescue
-        end
-        Lookbook::Preview.clear_cache
-        Lookbook::Engine.websocket&.broadcast("reload", {
-          modified: modified,
-          removed: removed,
-          added: added
-        })
-      end
-      @preview_listener.start
-
-      if Lookbook::Features.enabled?(:pages)
-        @page_listener = Listen.to(*config.lookbook.page_paths.filter { |dir| Dir.exist? dir }, only: /\.(html.*|md.*)$/) do |modified, added, removed|
+      preview_controller = Lookbook.config.preview_controller.constantize
+      preview_controller.class_eval { include Lookbook::PreviewController }
+
+      if config.lookbook.listen
+        @preview_listener = Listen.to(*config.lookbook.listen_paths, only: /\.(rb|html.*)$/) do |modified, added, removed|
+          begin
+            parser.parse
+          rescue
+          end
+          Lookbook::Preview.clear_cache
           Lookbook::Engine.websocket&.broadcast("reload", {
             modified: modified,
             removed: removed,
             added: added
           })
         end
-        @page_listener.start
-      end
+        @preview_listener.start
+
+        if Lookbook::Features.enabled?(:pages)
+          @page_listener = Listen.to(*config.lookbook.page_paths.filter { |dir| Dir.exist? dir }, only: /\.(html.*|md.*)$/) do |modified, added, removed|
+            Lookbook::Engine.websocket&.broadcast("reload", {
+              modified: modified,
+              removed: removed,
+              added: added
+            })
+          end
+          @page_listener.start
+        end
 
-      parser.parse
+        if config.lookbook.runtime_parsing
+          parser.parse
+        else
+          unless File.exist?(config.lookbook.parser_registry_path)
+            Lookbook.logger.warn "
+              Runtime parsing is disabled but no registry file has been found.
+              Did you run `rake lookbook:preparse` before starting the app?
+              Expected to find registry file at #{config.lookbook.parser_registry_path}
+            "
+          end
+        end
+      end
     end
 
     at_exit do
@@ -133,7 +152,7 @@ module Lookbook
       end
 
       def parser
-        @parser ||= Lookbook::Parser.new(config.lookbook.preview_paths)
+        @parser ||= Lookbook::Parser.new(config.lookbook.preview_paths, config.lookbook.parser_registry_path)
       end
     end
   end

data/lib/lookbook/parser.rb

@@ -2,27 +2,31 @@ require "yard"
 
 module Lookbook
   class Parser
-    YARDOC_FILE_PATH = Rails.root.join("tmp/storage/.yardoc").to_s
-
-    def initialize(paths)
+    attr_reader :registry_path
+    def initialize(paths, registry_path)
       @paths = paths.map { |p| "#{p}/**/*preview.rb" }
-      YARD::Registry.yardoc_file = YARDOC_FILE_PATH
+      @registry_path = registry_path.to_s
+      YARD::Registry.yardoc_file = registry_path
     end
 
     def parse
       YARD::Registry.clear
       YARD::Registry.lock_for_writing do
         YARD.parse(@paths)
-        YARD::Registry.save(false, YARDOC_FILE_PATH)
+        YARD::Registry.save(false, registry_path)
       end
     end
 
     def get_code_object(path)
       registry = YARD::RegistryStore.new
-      registry.load!(YARDOC_FILE_PATH)
+      registry.load!(registry_path)
       registry.get(path)
     end
 
+    # def yardoc_file_path
+    #   Rails&.root ? Rails.root.join(YARDOC_FILE_PATH) : YARDOC_FILE_PATH
+    # end
+
     class << self
       def define_tags
         YARD::Tags::Library.define_tag("Hidden status", :hidden)

data/lib/lookbook/version.rb

@@ -1,3 +1,3 @@
 module Lookbook
-  VERSION = "0.7.4"
+  VERSION = "0.8.0.beta.0"
 end

data/lib/tasks/lookbook_tasks.rake

@@ -1,6 +1,15 @@
 require_relative "../lookbook"
 
 namespace :lookbook do
+
+  namespace :previews do
+    desc "Preparse the previews"
+    task :preparse do
+      Lookbook::Engine.parser.parse
+      puts "Lookbook preview parsing complete"
+    end
+  end
+
   namespace :release do
     desc "Bump the Lookbook engine version number"
     task :bump_version, [:version] do |t, args|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lookbook
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.8.0.beta.0
 platform: ruby
 authors:
 - Mark Perkins
@@ -324,9 +324,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.2.22
 signing_key: